Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: Add facility to convert documents with pandoc #10

Merged
merged 2 commits into from
Mar 15, 2022
Merged

feat: Add facility to convert documents with pandoc #10

merged 2 commits into from
Mar 15, 2022

Commits on Mar 14, 2022

  1. feat: Add facility to convert documents with pandoc 

    Add a facility to, with relative ease, create OpenDocument Text and
Word documents from the original Markdown. To use, run

tox -e to-odt -- -o output.odt input1.md input2.md input3.md

or

tox -e to-docx -- -o output.docx input1.md input2.md input3.md

To achieve this, a simple script concatenates the input files, processes
them against mkdocs.yml using the Jinja2 CLI, and feeds the result to
pandoc with appropriate command-line options.

For branding, reference.docx and reference.odt files can be placed
into the pandoc subdirectory.

Also, add bashate testing for the script itself.
    @fghaas
    fghaas committed Mar 14, 2022
    Configuration menu
    Copy the full SHA
    2b1441f View commit details
    Browse the repository at this point in the history

  2. refactor: Remove Markdown admonitions 

    There are several issue with admonitions, or rather with the way they
are being rendered in the context of Material for MKDocs:

* Their font is smaller than the text body font, which is
  counterproductive for a piece of information that is meant to be
  emphasised.

* They use their own colour scheme, which is hard to align with
  branding.

* They use their own syntax which involves indentation, and thus
  hijacks what's otherwise meant for preformatted text.

* That specific meaning is lost on pandoc, which will render the
  admonitions as preformatted text in the process of converting to
  other formats.

Thus, remove the admonitions. Convert them to regular paragraphs when
appropriate; turn them into blockquotes when they do require
additional emphasis.
    @fghaas
    fghaas committed Mar 14, 2022
    Configuration menu
    Copy the full SHA
    d62071a View commit details
    Browse the repository at this point in the history