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

This article examines the advantages of using Emacs and Org Mode for drafting and exporting HTML articles intended for WordPress. It highlights how this workflow ensures total control over the markup, avoids superfluous tags generated by page builders, and allows for the advanced automation of the table of contents and structure. Practical guidance is also provided on configuring export options and correctly inserting the code into the editor.

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:

Features Block Editor (Gutenberg) Org Mode / HTML
TOC Generation Via plugin or dedicated post-publishing block Automatic upon export with configuration
Anchor Link Management Manual for each block/heading Automatically generated based on hierarchy
Code Cleanup Inclusion of comments and block attributes Minimal and clean HTML5 code

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.

Comments

Post a Comment

Popular posts from this blog

Two open source tools for editing PDF documents: GUI versus CLI.

Image
Table of Contents 1. Introduction 2. Managing operations with PDF Arranger 3. Managing the same operations with PDFtk. 4. In summary 1. Introduction The “PDF” is the essentially static document format par excellence. However, even PDF documents can be modified, especially with operations such as deleting, adding, reversing pages, inserting text, and more. There are various applications, including free ones, for performing these operations. In this article, I will report some parallel observations between two systems for page manipulation: one graphical, PDF Arranger, and one command line, PDFtk. PDF Arranger is a free and open source application (a fork of PDF-Shuffler) ideal for merging, splitting, rotating, and cropping PDF files in an intuitive way. PDFtk is one of the most powerful tools for manipulating PDFs in command line mode. I would like to point out that this article does not claim to be exhaustive on the two systems mentioned, but is onl...
Read more

MS Windows: xcopy and robocopy with mentions of batch procedures and rsync.

Image
Table of Contents 1. Copy and Paste: the universal method. 2. A short introduction to the Command Line in MS Windows. 3. Two integrated command-line solutions: xcopy and robocopy. 4. Basic scheme and some options, among many, of the robocopy command. 5. Robocopy and batch procedures. 6. Robocopy and Rsync. 7. FreeFileSync 1. Copy and Paste: the universal method. To transfer files from one folder to another folder we usually use “copy and paste.” The “universal method” is “copy and paste”: we all know how it works and it is certainly simple and straightforward. But is it also the most efficient method? If there were some documents already previously transferred and others to be transferred, it would be necessary to manually select those to be transferred before doing the “copy and paste,” and this operation could be particularly time-consuming. In cases like these, more efficient solutions should be sought. These solutions exist but are somewhat hidden...
Read more

About LaTeX, standalone, PDF and PNG

Image
1 LaTeX and the document format 2 Exporting documents from PDF to PNG. 3 Exporting images from PDF to PNG. 4 Examples 1 LaTeX and the document format As, of course, you all already know (:smiley:), LaTeX is a language dedicated to the typesetting of documents with state-of-the-art quality. It is, therefore, unnecessary to note that the basics of LaTeX can be learned in about 30 minutes, as illustrated in this page . For the purposes of this article, it is sufficient to recall that sources in LaTeX are composed of a preliminary part, also called the preamble , and the document with the contents. The format of documents generated by LaTeX is defined at the beginning of the preamble with the command \documentclass . The (probably) most widely used classes, such as article , report and book , produce documents in formats with predetermined sizes, specified by specific options, such as A4 (...
Read more