 One of the most powerful features of Emacs is org mode. Org mode is a form of markdown. It really is a powerful tool that allows you to do outlining and scheduling. And you can have these trees and subtrees within a document that you can fold and expand at wheel. Then you can create some really great tables. You can have source code blocks within a org mode document. And you can have the source code within those blocks evaluated. And you can have the evaluated source code. You can have that output directly into the document. Or you can have the output right to a file somewhere on your system. Really, org mode is Emacs's killer feature for most people that use Emacs. Like that's the one thing that separates Emacs from every other text editor on the planet. And today what I wanted to do is go through an example of how you rewrite one of your config files in org mode. So today what I'm gonna do is on camera, I'm gonna rewrite my Xmode add config in org mode. And I suggest you guys follow along with me. It doesn't have to be an Xmode add config. It can be any config on your system. As long as it's written in a proper scripting language such as Shield Script or Python or Lua or something like that or proper programming language, C, Haskell, E-List, whatever it happens to be. As long as it's written in a programming language. So, you know, simple configs like your i3 config or your Spectre WM config, they may not work because those particular config files are not written in a real language, right? They're written in a special syntax just for those particular window managers. But like your awesome config is written in Lua. That would work. Your Qtile config is written in Python. That would work. And of course my Xmode add config is written in Haskell and that will work. So all you need to do is pull up whatever config file you want to convert over to org mode, pull it up in Emacs. So let me switch over to my desktop and I'm gonna go ahead and open Doom Emacs. You guys know I use a distribution of Emacs called Doom Emacs. And let me go ahead and open up my Xmode add.hs. So this is my Xmode add config. Let me zoom in. And you know, this is just your standard Haskell document. And what I wanna do is I wanna rewrite this in org mode. I think it would be fun and I think it would make the document more readable because when you have a document written in org, when you upload it to something like GitHub or GitLab, GitHub and GitLab actually render org documents like the markdown, the org markdown that it handles all of that, it'll create the bullet points and the source code blocks and the table of contents and everything associated with org mode. So I think that is a really cool feature. So what I'm gonna do is I'm gonna go ahead and open up a vertical split here in Doom Emacs. So Ctrl WV will give me a vertical split. And then I'm gonna go ahead and launch the DearEd file manager inside Doom Emacs. So I'm just gonna do metaX and then type the word DearEd. You could have also just hit space FD in Doom Emacs. And then I want to go to .xmode add. That is the directory I wanna go to. And then in this directory, Ctrl X, Ctrl F, and it says find file. What I'm gonna do is I'm gonna go ahead and create a new file. I'm gonna call this file, readmeandallcaps.org. And the reason I titled it readmeandallcaps.org is by default the readme's on GitHub or GitLab are readme, all one word, uppercase. Typically it's readme.md for markdown, but you can do them in org. You don't have to do them in markdown. So I'm gonna create one in org. And you see at the top I get title is readme. And that's fine, we could change that if I wanted to. And I may go ahead and just change it. Xmode add config. Then the next thing I wanna do is I wanna go ahead and do another line here. And I wanna do the hash symbol plus sign and then do property. And then colon. And then I'm gonna come back and add some stuff to that in just a second. We'll get to what we're gonna do with that in just a second. But what I wanna do is I wanna take all of my Xmode add.hs and I wanna paste it over here. And then we're gonna edit it. So to copy the whole thing, what you need to do, gg, get you to the very first line of your Xmode add.hs, then go shift V to get into visual mode and then do capital G to go the last line. Hit Y to yank or to copy. And then when I go back over here and hit P, it pastes it. And let me zoom in here so we can see what's going on in this document. Now to actually make all of this Haskell code actually be evaluated as source code. We need to create some source code blocks. How do you do that? Well, what you need to do is you need to type the less than sign followed by an S and then hit tab on the keyboard and you get a source block. Now the very first line of the source block, the begin source, you need to specify what language Emacs needs to evaluate here. And in my case, this is Haskell. So begin source space Haskell and then in source, I'm gonna delete the in source line there and I'm gonna go down here and where do I want this to end? You know what? This is the very first source code block. I will end it right there. Let's just do our imports. So these are the Haskell imports. Do I really need this opening section here, all these comments? I might actually need that stuff. You know what? Let me get rid of the split here. I won't need my Xmonad.hs again. So let's just take a look at the org mode document. I think what I wanna do is now, let me get back into visual mode. These are all comments. I will no longer need these comments as part of the Haskell code. They can be outside the source code block and anything outside the source code block is naturally a comment. So because it's naturally a comment, I don't actually need the double dashes. So let's get rid of the double dashes. They're not needed. They would only be needed if I left the comments inside the Haskell block. So let's start an outline here. So I'm going to do a single asterisk for a top level heading and I'm going to do Xmonad config. And then these four paragraphs after that are just gonna be comments after this heading Xmonad config. And then we're gonna have our source code block. Now the source code block here, what I'm gonna do is I'm gonna add another top level heading. This will be imports, escape. And if I wanted to, I could write a description for this. So I wrote a little description explaining to anybody that comes across this document exactly what these imports are. You know, they're just modules that you need to import to make your config work. And then let's get rid of some of the lines within the Haskell source code block that I no longer need. So I don't need those comments because now I have the comments up here, you know, imports and then this comment here. And then I have my Haskell source code block. And then that's the end of the source code block. And then once we get to the end, we need another source code block. So less than S and then tab. And then once again, we have to specify a language because it could be something different than Haskell. Now you could actually have source code blocks of multiple languages in one org document. Then you could have, you know, the output from maybe a source code block that's written in bash output into the document and use that output to evaluate something in a source code block written in elist, for example. So it doesn't all have to have to be in one language. And now in this case, everything in this document will be Haskell. All the source code blocks will be Haskell. So let me delete the end source line because I need to move it down to right there. And this will be our next source code block. And so this will be our auto start. So what I'm gonna do is I'm gonna delete that line, delete that line, I won't need it anymore. Let's delete that one as well and paste this up here. And now what I'm gonna do is create another top level heading, so a single asterisk auto start. And if I wanted to, I could give it a description. So I wrote a description explaining exactly what the auto start block here is going to do. Let's get rid of the unnecessary spaces within that source code block. And then I could make the next source code block. And to see exactly what I've done so far, let's go back to the top of the document. So gg, if I do a shift tab on the keyboard, you see it folds the entire document because every heading I have already created is here. If I wanted to unfold them, shift tab again, do it twice and it will unfold the whole document. But I've only created three headings here. I need to create more, because I need to create one for workspaces, one for manage hook, one for log hook, and one for main. So let me go ahead and do those really quick. So what I'm gonna do to speed this up, I'm gonna copy this begin source line. I know I'm gonna need it right here, right here, right here, and then one right before the main. And then I need the end source line. So let me go back and I'm gonna copy the end source line and make sure I have an end source to every block. I'm gonna paste the end source line everywhere it needs to be. Make sure I've got all these source code blocks straightened out. Okay, and now let's space it out here. So we know exactly what's going on. Space after that one, space after that one. All right, now we need to go back and fix the titles. So this is the beginning of a source code block, and you see I had these comments originally in the Haskell, but I'm gonna do a delete here. Get rid of all that. I'm gonna put it right here before the source code block and then get rid of that line. We won't need that line or that line. And then in this line, I'm gonna go ahead and create the top level heading. And then if I get into a visual mode here, I can delete. Those, add a space there. I don't like the space in the blocks though. Let's get rid of all the spacing within the source code blocks. All right, and then we need to go ahead and do that one more time here. So let's go ahead and grab those. Gonna go ahead and put them right there. Get rid of that line, get rid of that line. Get into visual mode, get rid of those. And then log hook here needs to be a heading. So I'm gonna go ahead and add some space there. Get rid of that space there. And the very last thing is I need to create the heading for the main, create the heading there. Now we probably should do a description for the main. So I wanna head and wrote a description for the main. And now I have every section has a heading, a comment and then a source code block. Or at least it should. Let me double check. I didn't do one for workspaces. I missed this one. Visual line mode, do a delete and do a paste. Then let's go ahead and add a single asterisk to do that. And then into visual character mode, delete all those unnecessary dashes there. Gonna go ahead and write just to make sure this document is saved because we haven't actually done a save yet. I don't wanna lose any work in case anything bad happens. All right, I don't need these extra spaces. Here I'm just cleaning up the document a little bit. But now I think it looks pretty good. And this actually only took me about five or 10 minutes here. If I do a shift tab again, I can fold the entire document and it looks really good. Let me unfold it. The only thing is we haven't actually told org mode exactly what to do with this stuff. It says begin source Haskell. Well, what's it supposed to do with this Haskell stuff? It's gonna evaluate it and then do what with that evaluation. Well, what we're gonna do is come back to this property tag. Now, you could actually do this to each source code block, but because I want this applied to every single source code block, I want the same thing applied to it. It makes more sense to do this globally. And you do it globally with the property hitting here. Do header dash args space and do colon tangle space. And tangle basically says with these source code blocks, I want you to tangle it to this particular file, meaning I want you to take the output and write it to this specific file. What do I want you to write it to? Well, I want you to write it to xmonad.hs because that is the xmonad config file. So I want you to take my new org mode documentation that I wrote here and I want you to output all of this stuff to xmonad.hs. I'm never going to edit my xmonad.hs again. All I'm ever gonna do is come back to readme.org and readme.org is always gonna take these source code blocks of Haskell and output it to xmonad.hs. It's just gonna write it directly to xmonad.hs for me. Now it actually hasn't done this yet. What I need to do is somewhere at the top on title or property, put your cursor on that and do a control C, control C that refreshes. So control C, control C does a local refresh and do me max spits it out at the bottom where it says local refresh. And then the next thing you need to do is run org babble tangle. Now you can do meta x to get a search prompt and search for org dash babble dash tangle. There is a key binding for it here in do me max control C, control V, followed by a T. That's kind of a convoluted key binding for that. I probably would have trouble remembering that particular key binding. So I would probably just do meta x and then search for the command org babble tangle. Hit enter. And at the bottom it says tangled six code blocks from readme.org, it puts it in the status bar down here in do me max. So it tells you it tangled those six code blocks to xmonad.hs. So let me do another vertical split here and I'm gonna open up my xmonad.hs. And this is my new xmonad.hs. Remember before it had all the comments and everything in it? Now though, because we've tangled it, what it did is it took the source code blocks of that and rewrote xmonad.hs based on readme.org. I hope that makes sense. And now all I need to do is for my GitLab, I need to add readme.org to my GitLab and go ahead and push that. So I went ahead and did a quick push to my GitLab. I went ahead and pushed my new readme.org. And if I go to the browser, go to my GitLab page here, go to my .files repository. And in my .files repository, of course I have .xmonad somewhere in here, that particular directory. And now you have xmonad.hs, of course. And now you also have a readme.org. And the readme.org, because it's a readme file, is automatically put here in the screen and it renders it as proper org mode documentation. Now, one thing I don't like is I didn't add a table of contents. I should go back and fix that. So what I'm gonna do, let me get back into Doom Emacs here. So over here in the actual org mode document, well, let me close this because we won't need to see the xmonad.hs anymore. Because the table of contents won't actually be rendered into xmonad.hs, it's not actually gonna be source code. I just wanna create a new heading. I wanna create this heading here called table of contents. And then do colon, T, O, C, all lowercase, colon, at the end, hit enter. And then if I escape and do a write here, it automatically creates our table of contents, right? We don't have to do anything. If I clicked on main, watch what happens. I go to the main here at the bottom of the config, the readme.org, the gg to get back to the top. Of course, now I have seven or eight sections to my config here. I did notice that for all my headings, I did them in all caps. So just for consistency, I will rewrite the headings here. I don't like that one's just being xmonad config. I will do that about this config. I think that's a little bit more descriptive. Let me write, let me go to the very first line. I'm gonna do a control C, control C again to do a refresh. And then I'm gonna run org babble tangle one more time. Let me do a quick push to my GitLab. And let me go back to the browser and let's just refresh my xmonad directory here. And now we have a table of contents. Now the table of contents will not work here in GitLab. If I click on main, it actually doesn't take me down to the main section of the config. GitLab only recently started supporting org mode readmes. So GitHub handles this stuff just fine. If I was on GitHub, clicking main would actually take me to the main section of the config. GitLab, they still need to add that particular functionality. Now if these were external links, you know, the links to some other file in my dot files, it would take you to those. It just has a problem, I guess, taking you to other subheadings here in this particular document. And that's it, that's a literate config file that is basically rewriting a dot file as an org document. All I ever have to do now is edit my readme.org. And that's it. And I think this is such a better way because now it's so much easier to work on, especially if you have massive config files because you can fold them and unfold them and fold certain trees, one tree at a time. You don't have to look at all 2,000 lines or however long your config is. Those of you that have massive configs because I've seen some of those Emacs configs that are thousands of lines long and some of you guys running Tiling Window Manager. Some of you guys get really creative with how you configure your Tiling Window Manager. So once those things get several hundred lines long and certainly once you get into thousands of lines in length, rewriting it as an org mode document makes a lot of sense. Now before I go, I need to thank a few special people. I need to thank Michael, Gabe, Pablo, Nate, Corbinian, Mitchell, entropy UK, John, Arch5530, Chris, Chuck, DJ Donnie, Dylan, George, Louis, Omri, Paul, Robert, Sean, Tobias, and Willie. They are my highest tiered patrons over on Patreon without these guys this episode about rewriting your dot files as literate configs using Emacs in org mode. It wouldn't have been possible. The show is also brought to you by each and every one of these ladies and gentlemen, all these fine ladies and gentlemen. They're my supporters over on Patreon because there's no corporate sponsors here at DistroTube. I'm only supported by you guys, the community. If you'd like to support my work, consider doing so. You'll find DT over on Patreon. All right guys, peace.