Trouble shooters .Com® and CSS Primer Present:

Using Asciidoc or Markdown to Write Web Pages

See the Troubleshooters.Com Bookstore.


  • Introduction
  • Using Asciidoc or Markdown As Your HTML Generator
  • Introduction

    The Asciidoc and Markdown "Wiki languages" offer incredibly fast authoring and no need for the author to know HTML. The author needs CSS knowlege only if he or she wants to improve on the CSS that comes with Asciidoc and Markdown, or if for download speed or simplicity purposes they want to replace the voluminous CSS that is packaged with Asciidoc and Markdown.

    Asciidoc and Markdown are appropriate primarily for quick, content-only web pages in which appearance is secondary to content. That being said, both Asciidoc and Markdown enable the author to add raw HTML if desired.

    Using Asciidoc or Markdown As Your HTML Generator

    Many people turn to the Bootstrap tool because they consider hand-editing HTML too tedious, even if they use a zen-coding editor like VScode. To them I say, if you want a non-tedious and lightning fast way to make simple HTML, write your document in Asciidoc or Markdown and convert it. If you do this, don't use tables. Asciidoc's table creation is straight out of 1995, so that every cell flunks the W3C validator.

    For an Asciidoc and Markdown authored and converted HTML file to pass both and the W3C validator, a few of the early lines in the file must be modified. This can be done manually, or with a pretty simple AWK or Python program. The following describes the early line modifications for Asciidoc:

    1. Delete the line that begins with <?xml verson.
    2. Change the line that begins with <!DOCTYPE html PUBLIC to simply <!doctype html>
    3. Change the line beginning with <html xmlns= to the much simpler <html lang="en"/>
    4. Change the line beginning with <meta http-equiv="Content-Type" to the simpler <meta charset="UTF-8/>

    [ Training | Troubleshooters.Com | Email Steve Litt ]