From Org Mode to WordPress: writing articles in clean HTML by removing unnecessary code

1. Benefits of the Org Mode to HTML Workflow for WordPress Articles

In a few words: total control over the markup.

In particular:

  • No unnecessary tags or nested div elements automatically generated by the block editor (Gutenberg). Visual editors (such as Gutenberg in WordPress) and page builders insert a large number of invisible wrappers and containers necessary for the graphical management of blocks, transforming a simple title or paragraph into a complex, deeply nested structure.
  • A clear separation between structured content and CSS styling managed by the WordPress theme.
  • Redundant code increases page weight, makes CSS maintenance more complex, impairs accessibility (for screen readers), and can hinder search engines’ ability to parse the source code.
  • The source in .org format remains plain text, and as such can be edited with any text editor.

Writing in Org Mode and converting directly to HTML allows you to maintain clean, lightweight markup that closely follows the logical structure of the text.

2. Efficiency and Speed in Writing Thanks to Org Mode

Writing in Org Mode offers a number of additional advantages:

  • Use of advanced keyboard shortcuts for structuring text (headings, lists, tables).
  • Direct export to HTML using Org’s native functions (C-c C-e h h or C-c C-e h o).
  • Ability to manage metadata, categories, tags, and custom CSS directly from the file header options.

3. Managing the “Custom HTML” block vs. the Code Editor

  • Paste the exported HTML into a single Custom HTML block to prevent the visual editor from altering the formatting or removing specific tags.
  • Disable or be mindful of WordPress’s auto-formatting features (e.g., automatic insertion of unwanted tags such as <p> or <br>).

4. Advanced Management of the Table of Contents (TOC) and Structure

Regarding the table of contents (TOC), I note the following:

  • With block-based writing, you must first publish the article and then select the block for the table of contents.
  • With Org Mode, the table of contents is generated automatically during HTML conversion.

Here is a practical comparison:

5. Export Options Configuration: Table of Contents and Numbering

To tailor the HTML output to the requirements of a WordPress post, you can control the exporter’s behavior down to the finest detail using configuration directives included in the file header.

Specifically, by adding the line #+OPTIONS, you can manage the generation of the table of contents and the numbering of headings:

#+OPTIONS: toc:2 num:nil tags:nil

Here’s what these parameters do specifically:

  • toc:2 (Table of Contents): Determines whether an automatic table of contents is generated and how deep it goes. Setting it to 2 causes Org Mode to generate a table of contents that includes headings up to the second level (e.g., level 1 and 2 headings), automatically placing it at the desired location in the document. You can disable it completely by setting it to nil (toc:nil).
  • num:nil (Heading Numbering): Disables automatic numbering of headings (1, 1.1, 2, etc.). For a blog post or web page, unnumbered headings provide a cleaner, more modern visual appearance, leaving it up to the WordPress theme’s CSS stylesheet to format them graphically.
  • tags:nil (Tags): With this setting, tags will remain visible in the Org Mode source file but will be omitted from the generated HTML. This option is very important because it allows you to maintain the search functionality for tags in Org Agenda without having them appear in the version generated for web publication.

These guidelines, combined with metadata such as #+TITLE and #+LANGUAGE: it, allow you to fully automate the preparation of the HTML code even before exporting it to the platform.

6. Input Methods: Code vs. Visual Editor

When pasting HTML exported from Org Mode into WordPress, it is essential to switch to the text editor’s Code mode (or insert the text into a Custom HTML block).

You must avoid using the Visual editor in this workflow: since it interprets HTML as plain text, the visual editor would escape tags (for example, converting the characters `<` and `>` into HTML entities) or insert unwanted automatic formatting and paragraphs, thereby invalidating the clean structure generated by Org Mode.

7. Conclusion

Writing in HTML—that is, in plain text—on WordPress allows for thorough control over the cleanliness of the code and, consequently, over the article’s content.

Generating HTML from Org Mode allows you to automatically create a table of contents and internal and external links, which are generated directly during the export from Org Mode.

It’s therefore worth giving an “opportunity” to an article-writing system based on Emacs, Org Mode, and HTML, which can be used on WordPress or any other similar platform.

Thank you for your attention.