How to Design a Blog with Emacs and Org-Mode

It can be tempting to immediately start writing content that you’ve been eagerly waiting to write (as I had done), but you will save time in the long run if you hold off from that and spend a few minutes to read and learn how to utilize good writing advice.

• Every post should have a meaningful topic. It’s also helpful if everyone else writing about the topic is missing a key point or over-complicating simple things.
• It’s important to plan and outline your content before writing it. Many bloggers just write whatever comes off the top of their heads, which causes their posts to lack structure and organization. I was guilty of this myself for some of my essays since I was so eager to put my ideas out there, until I restructured them.
• Many people have a tendency to write long sentences with cohesive devices that place restrictions on how they write their sentences. For such people (including my former self), I recommend taking Scott Adam’s Writing Advice to heart. Writing shorter sentences is an important key for writing better, especially if the goal is to create information dense content with little fluff. Fluff writing makes content longer to read, harder to understand, and it may bore the readers.
• Humans are psychologically attracted to reading lists for multiple reasons. Lists are also easier for people to read and follow, rather than reading paragraph after paragraph, if it’s possible to format the content that you want to write that way.
• If you need to list a bunch of short ideas, reasons, or arguments in a section, it’s a good idea to use bulleted or numbered lists. Paragraphs require adding more cohesive devices and other fluff language compared to lists. As an example, some sections in my Overpopulation FAQs became more concise and easier to read when written as lists instead of paragraphs.
• HTML Quotation Elements are a great way to quickly state opposing points of view before addressing them. I’ve made my Case Against Libertarianism essay and other works less wordy by using them.
• Wikimedia Commons provides millions of freely usable images that people can use in their works, provided that they respect the terms of the licenses. See my section for links for learning more about copyrighting and licensing.
• Lastly, taking at least an hour to learn good SEO practices can save you the trouble of rewriting your content later on, if you want to maximize your number of readers.
• Why You Should Start a Blog Right Now - Alex Guzey; This webpage gives encouragement for starting your own blog. It also argues against some common excuses made for why someone shouldn’t start a blog.

For most topics, I don’t understand bloggers who write posts every day. For one thing, there’s probably a finite amount of good ideas out there to discover, due to the physical materialist nature of the Universe. For another thing, it’s unusual for someone to observe or brainstorm something really interesting or noteworthy every single day that is worth writing an entire post about. Even if someone did write a blog post every day, the average quality of each post would have to be quite low since such a high frequency of content production would require espousing fewer good ideas in each post.

I don’t have the time to write a new post each day, but even if I did, eventually hundreds or even thousands of blog posts would accumulate over time. If a newcomer came across such a blog for the first time, they would be lost and unsure of where to start reading since it would be difficult to navigate and determine which posts are worth reading.

Most people who want to start blogging and aren’t using a Content Management System like Wordpress or Blogger should consider downloading and using a static site generator (SSG). In my opinion, the main benefit to using SSGs is that they make it possible to use Markdown (or Org-Mode) instead of HTML to create webpages, but they also provide many other benefits.

Org-Mode wasn’t specifically designed to be a static site generator, but one can configure it to do many of the key features that a SSG can do. Thomas Ingram and Dennis Ogbe have written their own guides on how to use org-mode as a static site generator for websites. Their tutorials are more complex than mine, and their resulting websites have more features, like sitemap and RSS feed generators, blogging templates, more detailed headers and footers, etc. There are also other guides that show how to set up tagging systems for posts. However, I’m not experienced enough with Elisp and my website may not need those features, so some people may prefer my simpler tutorial here.

Since I already knew how to export my .org files to HTML webpages, I never used a different SSG when I created this website, and I still don’t. The reasons are complicated, but I encountered multiple problems when I last tried to switch to using a more full-fledged SSG in July 2023:

• It would take too much time for me to learn how SSGs work, how to configure them, and how to use them. I already have a system for creating and publishing my webpages that works me.
• I’d have to program Emacs keybindings for operating the SSG, lest I would have to use my command terminal to operate the SSG instead, which is inconvenient because then I’d have to frequently switch between applications. This would be hard because I’m terrible at Elisp (and programming in general).
• Most static site generators use Markdown instead of Org-Mode. Although Hugo is compatible with org-mode, there weren’t enough tutorials and documentation for showing how to use Hugo with org-mode when I tried to switch over. It’s possible that Hugo may develop better documentation for writing with org-mode in the future.
  • Hypothetically, I could switch to using Markdown to write my webpages, but that would take time, it could create confusion and syntax errors if I switch, and most importantly, I’d lose the ability to export my .org content to other formats, like .tex, .pdf, .txt, .odt, etc.

There are still some benefits for creating and publishing content that SSGs would provide compared to my current system:

• SSGs could provide my website with better headers and footers.
• SSGs provide tags for sorting webpages, which makes them easier to navigate.
• SSGs have ways to prevent the website directories from displaying in the URLs.
• It would be easier to create RSS feeds.
• They provide templates for writing webpages.
• They provide text summarizers for writing webpage descriptions and such.
• They could create a search index that readers could use to search my website’s content. Thus, the search bar on my homepage wouldn’t have to use an external search engine like DuckDuckGo.
• They can create better image galleries.
• There are many other plugins for SSGs that make it easier to create content.

However, even after considering all the benefits that I could potentially gain, I decided that it still wasn’t worth it for me to stop using my current setup. Another thing is that my website doesn’t really need some of these features (even if they’d be nice), and I have found other ways to get most of the benefits that other SSGs would provide, which I talk about in this article.

In my opinion, org-mode is the best and most versatile markup language there is. Resources for learning how to use org-mode syntax include:

• Xah Lee’s Org Mode Markup Cheatsheet.
• The Org-Mode Compact Guide.
• The Org-Mode Manual.

Hopefully, this guide will be detailed enough to show other people how to replicate the design process. It will assume that that the reader is already familiar with the basics of using Emacs. If the user has no interest in using org-mode or Emacs, then most of the CSS, SEO, and Recommended Tools sections of this article may still be of interest to the reader.

Org-mode variables control how the org-mode markup language will be exported to HTML and other formats. They can be set either within the file itself as file local variables, or within your .config/doom/config.el, (or ~/.emacs.d/init.el for non-Doom-Emacs users). For a complete list of variables controlling how org-mode exports files, see the following links from the Org-Mode Manual:

• Export Settings
• HTML-Specific Export Settings
• Property Options For Org-Mode File Exports

There are multiple reasons to set org variables with config.el instead of within file local variables:

• It makes the compilation of your org files less prone to errors, assuming that you export a lot of them.
• It ensures that all org files export the same way each time, aside from any customizations using local file org variables.
• If you later decide to that you want to change something across all your .org files, it’s easier to just edit one file (config.el) instead of editing every single org file.
• If you’re only going to export org file variables for one purpose or similar purposes, then you don’t have to copy as many local org file variables to each new file to do the same things, and the org files will collectively take up less file space. This also gives the beginnings of the org files a cleaner appearance.

I have the following settings configured for org-mode in my config.el. The user can learn more about what each variable does by pressing SPC h v in Doom-Emacs, or C-h v in regular Emacs.

(setq org-src-fontify-natively t)
(setq org-hide-emphasis-markers nil) ;; Don't hide the /, *, and _ font formatting characters.
(setq org-startup-folded t)
(setq org-startup-truncated nil)
(setq org-startup-with-inline-images nil)
(setq org-return-follows-link nil)

(setq org-html-doctype "html5")
(setq org-html-html5-fancy t)
(setq org-html-content-class "content")
(setq org-html-container-element "div")
(setq org-html-head-include-scripts nil)
(setq org-html-head-include-default-style nil)
(setq org-html-head-extra "<link rel=\"stylesheet\" type=\"text/css\" href=\"/style.css\">")
(setq org-html-link-home "/")
(setq org-html-link-up "/")

(setq org-export-with-author t)
(setq org-export-with-email nil)
(setq org-export-with-creator nil)
(setq org-html-metadata-timestamp-format "%Y %B %d, %H:%M")
(setq org-html-postamble t)
(setq org-html-postamble-format
 '(("en" "<p class=\"date\">Last Modified: %T</p>\n
          <p class=\"author\">Author: %a</p>"
  )))

And the following is the entirety of the org-mode keywords and values that I include at the beginning of every .org file for controlling the HTML code of my webpages:

#+title: The_Webpage_Title_That_Will_Be_Placed_In_Both_<title>_and_<h1>
#+subtitle: The_Webpage_Subtitle_That_Will_Be_Placed_In_<subtitle>
#+author: The Author Name
#+description: The webpage description (up to 160 characters long).
#+html_head: [Javascript code for adding Google Analytics to the webpage]
#+html_head: <meta property="og:url" content="[the canonical URL link for this article]">
#+html_head: <meta property="og:type" content="article">
#+html_head: <meta property="og:image" content="[Link to image file]">
#+options: ^:nil

Org-mode provides two different variables for adding code to the <head> section of HTML files, org-html-head and org-html-head-extra. They’re also written as #+html-head and #+html-head-extra, when used as local file variables written at the beginning of org files. The reason why there’s two different variables is because people will often want to embed a lot of code to <head>. If there were only one variable for adding code to <head>, someone had assigned a value to org-html-head inside their config.el, and they also tried assigning additional values with #+html-head in their local files, then the values written in the local files would overwrite the values for org-html-head inside their config.el so that they wouldn’t display at all. Fortunately, the two separate HTML head variables can be used strategically to prevent this. In my config.el, I have:

(setq org-html-head-extra "<link rel~\"stylesheet\" type~\"text/css\" href~\"/style.css\">")

Meanwhile, my local file org variables add the following HTML <head> code to each file:

#+html_head: [Javascript code for adding Google Analytics to the webpage]
#+html_head: <meta property="og:url" content="[the canonical URL link for this article]">
#+html_head: <meta property="og:type" content="article">
#+html_head: <meta property="og:image" content="[Link to image file]">

These settings ensure that all the content that I want to be added to HTML <head> will get included.

Every time I want to re-export the HTML output from my org file to update my webpages, I press SPC m e h h in Doom-Emacs, which executes the command org-export-dispatch.

When creating links in org-mode, there are many options and they depend on what you’re linking to. Since I often want to link to section of my website pages, I always insert the following org syntax under each section heading. Without the following syntax, the fragment identifiers will change every time the org-mode code is re-exported to .html.

:PROPERTIES:
:CUSTOM_ID: Name_Of_Fragment_Identifier
:END:

This syntax makes it possible to have consistent fragment identifiers once the webpages are published, and users can find them when clicking on links in each webpage’s table of contents, and copying the URL.

When writing paragraphs in org-mode, I prefer to place each sentence on a separate line (i.e. every line ends with a newline character). The text will not be displayed as separate paragraphs unless there are at least two newlines between each line. The advantage to this is that it makes it easier to easier to rearrange the sentences in my paragraphs, easier to merge and/or divide paragraphs, and easier to convert between paragraphs and bulleted lists (compared to keeping all of a paragraph’s sentences on just one line). This style for formatting paragraphs and sentences and the recommended minimalist writing advice both compliment each other quite well.

If an .org file contains content that I don’t want to publish just yet, I can temporarily comment that text out before exporting the .org files to .html. This facilitates the organization of all my files since I can organize all my ideas by file, without having to publish everything that I write.

I don’t usually export my org files to LaTeX, but I do so when I want to get my works in PDF format. When exporting .org files to LaTeX, I include the following line at the beginning of the .org file so that the page margins don’t take up so much space in the resulting .pdf file.

#+latex_header: \makeatletter \@ifpackageloaded{geometry}{\geometry{margin=2.5cm}}
{\usepackage[margin=2.5cm]{geometry}} \makeatother

For people who create YouTube videos to accompany their blogs, W3 Schools has a page that details the HTML code for embedding YouTube videos into webpages. In org-mode, C-c C-, (or SPC m e h in Doom-Emacs) will execute the command org-export-dispatch, which will insert the lines for exporting the <iframe> HTML code:

#+begin_export html
<div align="center"><iframe allow="fullscreen" width="420" height="315"
src="https://www.youtube.com/embed/VIDEO_TAG_GOES_HERE"></iframe></div>
#+end_export

If you wish to create a custom, complex table in HTML, then I recommend using tablesgenerator.com. It provides a GUI for generating HTML/LaTeX/Text/MarkDown/MediaWiki code to create a table with however many rows and columns you want, merging and splitting cells, setting CSS of each table cell, and transposing the table with a single click. I personally think it’s much easier to create tables this way, rather than having to painstakingly perfect non-WYSIWYG code.

People who are using org-mode to create webpages can use the CSS Support section from the Org-Mode manual to inform them of all the ID attributes and classes that are available for tweaking a webpages’ CSS, using a separate CSS file. Alternatively, some users may prefer to use the default org-mode CSS with their files. If you wish to use it, you must have the following line in you config.el:

(setq org-html-head-include-default-style t)

Or you could set it with an org local variable by placing the following line in their org file:

#+options: html-style:t

However, the default org-mode CSS has a total of 7.0kB, and it will be included into every HTML file that you export where the html-style variable is turned on. It may also complicate or interfere with your own CSS customizations if you link a separate CSS file to your HTML exports. My advice is to write your own CSS file, and view the output of the default org-mode CSS and copy the useful parts of it that you want to keep for your own custom CSS file.

If you would like to overrule the default CSS alignment of the tables, you can use ‘<r>’, ‘<c>’ or ‘<l>’ in a special table cookies row of the table. You may also combine alignment and field width like this: ‘<r10>’.

The CSS file that I use to style my org-mode generated webpages is available under the CC BY 4.0 license. To download the template, just click the link below, and press “Ctrl + S” to save it.

  Download Zero Contradictions Org-Mode CSS Essays Template

Anyone can use this CSS template for their own creations as long as they keep the line that attributes me within the file and summarize what they changed (if anything).

In the interest of creating a bloat-free Internet with aesthetic webpages and minimalist designs, I (Zero Contradictions) have decided to release an HTML template that replicates the layout, design, and functionality of my homepage under the CC BY 4.0 license. Other people may use this HTML template to create their own webpages if they wish, as long as they leave the attribution text to Zero Contradictions in the footer. To download the template, just click the link below, and press “Ctrl + S” to save it.

  Download Zero Contradictions Homepage Template

The following bullets are instructions for how to customize and build upon the template: Instructions For Customizing The Template:

• Open the “homepage-template.html” file with a plain text editor, such as Notepad.
• [[double square brackets\]] are placed around the text that needs to be changed in the file so it’s easy to find all the meta (unseen on the page) information. To add new links and change the information, you’ll want to have a bit of experience with HTML.
• Start scanning for double brackets and fill in the information as needed. Make sure the <title> text has words that tell search engines what you’ve got going on the page. Fill out those meta tags too, for better SEO.
• If you’ve chosen a logo or image to represent your website, use realfavicongenerator.net to generate all the favicons needed for this code to be useful. Place the favicons into the website’s root folder.
• If you want to verify your website with Google Search Console, you should visit Google Search Console’s Welcome page, click URL prefix, enter your website’s URL, and follow the instructions for adding the verification meta tag to your homepage.
• Likewise, if you want to add Google Analytics to this page, you should follow these instructions to setup a Google Analytics account and get the code to be added within this page’s <head> tag.
• Unless you’re familiar with CSS, just leave everything between the <style> and </style> tags alone. If you are familiar with CSS, go crazy!
• For the link colors, I’ve left two different color schemes to choose from, and I’ve explained the pros and cons to both of them inside the template itself. If you want to switch to the other scheme, just uncomment the CSS for the other scheme, and comment out and the CSS for the Cretan color scheme.
  • Although the link colors are set up to mimic the functionality of the link colors on ZC’s website, you could give different purposes, as long as you change their names (blog-posts, videos) everywhere in the .html file to reflect those purposes.
• Now, your header image. Just put the filename of the image you’re going to use after src=“ and make sure the image is placed in the same directory on your host as this file. Type in a description of the image as well while you’re at it. The image will resize to 160 pixels wide automatically. Or you can delete the whole img tag if you don’t want to use one.
• Fill out the information for introducing the webpage as you please.
• Next, within <nav> tag, you should fill out the category names for the links that you want to display. You may want to also edit the href attribute values in each <a> tag to help your users navigate the site. The text after each hashtag <#> will be displayed in your website’s URLs.
• If you want to keep the Javascript code for searching your website site with DuckDuckGo, you should place the canonical URL for your website on the line with query.value = "site: ". Be sure to leave a space before the end quote so that DuckDuckGo can search your website correctly. It may take a few days (possibly weeks) after the website is up and running for DuckDuckGo to index your website, before the search bar works correctly.
• Now, you’re ready to plug in your links. Each link is in its own <li> tag to keep them on their own line and to give a little space in between. Just replace the text after href=“ with the direct URL (including http://) and replace the next set of brackets with the text you want to appear on the page. You’ll notice that the first link in the left column has a paragraph right after it but before the closing tag. Make sure to follow this syntax to keep the spacing kosher.
• Want to add another link? Just copy and paste one of those <li>…</li> rows wherever you want it to be. Deleting a link is the opposite.
  • I’ve provided many different format styles for the types of links that you may use for this page as you build from this template. There format styles vary across the categories, so just cut and paste which format types you want from the available links.
• Add a new separating header with <h2>…</h2> or <h3>…</h3> tags wherever you’d like (but, of course, within one of the columns).
  • If you want to add new headers to the navigation bar, then be sure to add list items and links within the <nav> tag accordingly.
• Want to add a separator line? Figure out where it should go and place an <hr> right there.
• img tags can also be used in columns, just make sure they are in between the <li> and </li> tags. Style wise, it’s probably better to put img tags in between the <li> and the <a> tags.
• Scroll down to the bottom for the footer links. Don’t want any? Just delete them all.
• Other information and advice for customizing the template may be found within the template itself and the this blogging advice page.
• If you plan to use this template as your homepage, or as the default webpage for a web directory, rename the file to “index.html” and place it in the home folder of your chosen web host.

And that’s it! To make it live, just copy index.html to a public folder on your web host and check it out. If you already have a website going, be careful where you put this so you don’t overwrite the main site file.

Although the terms in the Creative Commons license say that you have to explain what you’ve changed, it seems that most people outside of the Wikimedia project don’t do that in practice when they change content released under a CC license (although they should). For this HTML file, I will let that condition slide. Since this file is meant to be a template, it’s already easy to figure out what the changes to it were. Listing the changes would only make the template inconvenient to use, and the only thing that matters to me is that people attribute me if they decide to use it.

This template is based on the JoshCanHelp Drudge Report template, which is available in the public domain if you would prefer to create a webpage with a more simplistic design that does not require attributing the original author.

• Copyright Exclusive Rights For U.S. Law
• What’s the Difference Between Copyright and Creative Commons?
• Fair Use - U.S. Copyright Office

In general, you should be careful where you find images and other content used within your works and how you source them. With the advent in AI technology, there has been a substantial increase in threatened and actual litigation involving CC licensed works, thanks to companies like Pixsy. These days, there are more and more bots and companies every day whose job is to scour the web looking for people to litigate against, and they’ll only become more powerful, while you probably won’t.

It’s recommended that all users of creative commons works follow the Best Practices For Attribution to protect themselves and share the content that they want to share.

The Creative Commons Licenses are a set of copyright licenses that allow creators to share their work with others while retaining certain rights and control over how their works are used. These licenses were designed to facilitate a flexible and legally sound way to grant permissions to the public for using creative works, such as text, images, music, and other intellectual property. Creative Commons licenses are widely used to promote collaboration, creativity, and the sharing of knowledge on the internet.

There are several different Creative Commons licenses, each with different permissions and conditions, represented by a combination of symbols and abbreviations. The primary components of these licenses include:

• Attribution (BY): This is a common element of all Creative Commons licenses. It requires users to give appropriate credit to the original creator of the work. This credit should include the creator’s name or pseudonym and a link to the source if applicable.
• Non-Commercial (NC): This element allows creators to specify that others can use their work, but not for commercial purposes. If the “NC” element is included, users cannot use the work for profit without obtaining separate permission.
• No Derivatives (ND): Creators can choose to restrict others from creating derivative works based on their original work. If “ND” is included, users can share and redistribute the work but cannot make changes to it.
• Share Alike (SA): This element permits others to use, modify, and distribute derivative works, but any new works must be released under the same license terms as the original work (or a compatible license). This is sometimes referred to as “copyleft” and encourages the creation of open and collaborative content.

The combination of these elements allows for the creation of various license options, such as:

• CC BY: This is the most permissive Creative Commons license, allowing others to use, modify, and distribute the work for any purpose, as long as they provide proper attribution to the creator.
• CC BY-SA: Similar to CC BY, but it also requires derivative works to be licensed under the same terms (Share Alike).
• CC BY-NC: Allows others to use and modify the work but not for commercial purposes.
• CC BY-NC-SA: Combines attribution, non-commercial use, and share-alike requirements.
• CC BY-ND: Permits redistribution of the work as-is with proper attribution but without making derivative works.
• CC BY-NC-ND: Permits redistribution of the work as-is with proper attribution but without making derivative works.
• CC0: A public domain dedication tool that allows creators to waive all their copyright and related rights in a work.

The CC Deeds explain what the licenses allow for licensees and licensors in layman’s terms. But every creator and user should read the CC licenses’ legal terms, especially if they are unsure of what they can and cannot do with licensed content.

Every Creative Commons license requires people to attribute the originals creators of the work, and to state what they changed from the original work. The only exceptions are the ND licenses which forbid changes of any kind, and the CC0 license which releases works into the public domain. The main difference between the CC0 license and the CC BY 4.0 license is that the CC0 license doesn’t require users to attribute the authors or explain what they’ve changed from the original work (if anything).

More Info: Creative Commons FAQs

The Creative Commons License Chooser can help you choose a CC license. See: advantages to using the CC license chooser.

Before you license anything under CC licensing, you should first confirm that it’s appropriate:

• [ ] I own or have authority to license the work.
• [ ] have read and understand the terms of the license.
• [ ] understand that CC licensing is not revocable.

The CC license chooser can help generate Creative Commons Rights Expression Language (CC REL) metadata that can be embedded into your online works, which can help search engines and such more easily identify the licensing of your content.

Here are some links that provide more information on enforcing CC licenses and preventing copyright infringement:

• Creative Commons Licensing Enforcement
• Creative Commons Licensing Enforcement Principles
• What to Do if Your CC-Licensed Work is Misused - Creative Commons
• How To File A DMCA Takedown Notice

Nothing on this page or website should be considered legal advice.