{"id":21844169,"url":"https://github.com/electronstudio/markdown_comparison","last_synced_at":"2026-05-19T15:13:37.595Z","repository":{"id":122565101,"uuid":"385873629","full_name":"electronstudio/markdown_comparison","owner":"electronstudio","description":null,"archived":false,"fork":false,"pushed_at":"2021-07-19T01:34:51.000Z","size":9848,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-26T11:42:12.178Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electronstudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-14T08:49:15.000Z","updated_at":"2021-07-19T01:34:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"9af8db04-831c-482a-87c3-3e0122480255","html_url":"https://github.com/electronstudio/markdown_comparison","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electronstudio%2Fmarkdown_comparison","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electronstudio%2Fmarkdown_comparison/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electronstudio%2Fmarkdown_comparison/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electronstudio%2Fmarkdown_comparison/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electronstudio","download_url":"https://codeload.github.com/electronstudio/markdown_comparison/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244825652,"owners_count":20516592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-27T22:18:38.649Z","updated_at":"2026-05-19T15:13:37.539Z","avatar_url":"https://github.com/electronstudio.png","language":"TeX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Comparing Markdown, Asciidoc and ReST for producing a PDF book\n\nI want to know which format I should use to write my next book, so I wrote a chapter in several formats and used several programs to produce PDFs to copmpare.\n\nThe formats: Markdown (Pandoc variant), Markdown (Softcover variant), Asciidoc, ReStructuredText\n\nThe software: Pandoc (with and without Eisvogel template), Softcover, Asciidoctor, Sphinx.\n\n# Pandoc-flavoured Markdown (Pandown)\n\nI'm going to call the Pandoc variant of Markdown *Pandown* to avoid confusion with Pandoc the software and confusion with the standard Markdown format.\n\nThe lowest common denominator. Easy syntax to write. Used everywhere.\n\nYou would think it would easy to convert to any of the alternatives using Pandoc because they all have a super-set of Markdown’s features, but if you don't stick to core Markdown and use any of the Pandown extensions you will need to do additional work every time you convert.\n\nLack of standardisation is the issue. Pandown adds extensions for image sizing and code highlighting but if you use these then other programs like Jekyll (and GitHub pages) will display the codes they don’t understand.\n\n????However the code listing stuff is hacky, and it’s impossible to fully control page breaks.\n\n## PDF Output\n\nPandoc: ok, could use some template tweaking\n\nPandoc+Eisvogel: good.\n\nSphinx: poor, because Sphinx doesn't understand Pandoc extensions.  (It has it's own equivalent extensions in myst_parser, but Pandoc, Github, etc won't understand them, so then you might as well just write in ReST.)\n\n\n#  Softcovered-flavored Markdown (Softmark)\n\nSoftcover is a program that coverts Markdown to PDF via Latex. Unusually, HTML (and ePub) is then produced from the Latex. The result is a great looking PDF book but you don't have as many options when it comes to styling the HTML as you do with the other programs.\n\nThe extensions over basic Markdown work by you inserting Latex into your document, and you will have to do that to get a nice layout, so it’s perhaps not very portable and not very widely used.  However if you were considering writing your book in your Latex anyway this is easier, especially if you've already been writing Markdown.\n\n## PDF Output\n\nSoftcover: good, but requires adding page break hints to prevent weird layouts which I haven’t done yet.\n\nNo other programs will read softcover markdown.\n\n## Converting from Pandown to Softmark\n\nThis has to be done manually.\n\nSoftcover can't deal with yaml metadata at the start of the document, so it has to be removed (and put into a `config.yml` file.)\n\nLine highlighting format is different, but overall better because you can combine syntax highlighting with\nline highlighting.  Instead of `{emphasize=5-7}` you replace with `\n```gdscript, options: \"hl_lines\": [5, 6, 7]`\n\n\nNot possible to specify image sizes.  So have to delete every occurance of `{width=70%}`.  The images are then too big and also the captions are not shown.  To fix this, convert them all to figures which are sized automatically by adding labels to the caption, e.g. `![Caption\\label{fig:image}](image.png)`\n\nYou can then also insert references to them `\\ref{fig:image}`.\n\nLinks don't display the URL in the PDF output.  Have to manually add them as footnotes.\n\nNumbered lists often get messed up by Softcover attempting to helpfully replace your numbers with ones it thinks are better.  Mostly this is fixable by careful indenting, but for code listing you must not indent and you must remove any empty lines between the code and the paragraph above.\n\n# Asciidoc\n\nFairly nice looking syntax that is partly compatible with markdown.\n\nAdds things like sidebars that are useful in books.\n\nFor PDF output they originally converted to docbook and/or latex first. I haven’t tried this method but it’s depreciated. Currently they generate PDF directly from asciidoc. I\n\n## PDF Ouput\n\nAsciidoctor: pretty nice. Fonts can be customed easily.\n\nHowever it doesn’t look quite as nice as Latex. The default templates don't look good and it took me quite a while to customize them myself - I couldn't find any ready-to-print examples to copy online.  Footnotes at bottom of page aren't supported but they are working on improving this.\n\nSurprisingly, Pandoc has not yet implemented support for reading Asciidoc, so Asciidoctor is probably your only choice of software.\n\nTodo: try converting to Docbook and then to PDF from there.\n\n## Converting from Pandown to Asciidoc\n\nConversion from pandoc is mostly automatic.  Just add headers to file:\n```\n= Godot High Score Tables\nRichard Smith\n:source-highlighter: rouge\n:doctype: book\n:toc:\n```\n\nCode line highlighting is easy but doesn't convert because it's not a standard part of pandoc, it's an extension.  So have to insert `[source,gdscript,highlight='4-4']` above listings you want\nlines highlighted.\n\nImage captions don't get convert converted correctly, need to fix every image.\n\n\n\n# ReStructuredText (RST)\n\nProbably the most advanced, and used by big projects like Python and Linux, but the syntax is horrible.  It can read Markdown files but I don’t think you can mix and match in the same file (?).\n\nConverting from Pandoc Markdown mostly works - just needs a book title added at the top.\nImages are given alt tags which are sometimes too long and cause errors.\n\n## PDF Output\n\nSphinx: the default template is quite poor, but after doing some tweaking the results are good.\n\nPandoc: ok, almost the same as using Markdown (Pandoc)\n\nPandoc+Eisvogel: good, almost the same as using Markdown (Pandoc)\n\n\n\n# Verdict\n\nPandoc probably *could* do everything, but you would have to install lots of non-standard extensions and/or write your own templates, so if you want to stick to standards and supported-out-of-the-box advanced formatting, you will need to use one of the others.\n\nAsciidoc is my favourite syntax, but the PDF software isn't *quite* ready yet, so can't recommend it, and so  ReStructuredText beats it currently.\n\nReStructuredText can also give you the same output that Markdown (Pandoc) gives by using the same software, in addition to what you can produce with Sphinx.  Therefore strictly RST beats Pandown too.  However it is not as easy to write so you might still choose Pandown if you don't need all the features.\n\n\n# Features Comparison\n\n|            | Pandown | Softmark | Asciidoc | ReST |\n| -----------| ------- | -------- | -------- | ---- |\n| Hyperlinks | 1       | 1        | 0**        | 1    |\n| Footnotes  | 1       | 1        | 0        | 1    |\n| Line highlight | 0*   | 1        | 0        | 1    |\n| References | 1       | 1        | ?        | 1    |\n| Figures    | 1       | 1        | 1        | 1    |\n| Admonitions| 0*       | 0        | 1        | 1    |\n| Sidebar    | 0        | 0        | 1        | 1    |\n| **Total**    | 4       | 5       | 4        | 7    |\n\n\\* there is an extension available but it's either not complete or difficult to install\n\n\\** You can get hyperlinks to display if you enable `:media: prepress` but they look pretty horrible because of the lack of footnote support.\n\nTODO: look at citations and equations for more academic documents.\n\n# Subjective Output Quality Comparison\n\n|            | Pandown | Softmark | Asciidoc | ReST |\n| -----------| ------- | -------- | -------- | ---- |\n| PDF        | 9       | 10        | 9       | 10    |\n| HTML       | 10      | 8        | 9      | 10    |\n\nNote that Asciidoc and ReST do requring tweaking to achieve this nice PDF.  For HTML I'm mostly\ncomparing the quantity of themes that are available.\n ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectronstudio%2Fmarkdown_comparison","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felectronstudio%2Fmarkdown_comparison","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectronstudio%2Fmarkdown_comparison/lists"}