Sign inSign up

macwinnie/md2rst

By macwinnie

•Updated 3 days ago

Image that supports building documentation from MarkDown within phpDocumentor ...

Image
0

2.9K

macwinnie/md2rst repository overview

⁠md2rst

This repo holds the Dockerfile to support phpDocumentor and translate md (MarkDown) files into rst (reStructuredText) files.

⁠environmental variables

variable namedefaultdescription
FROM_DIR/datadirectory where the script reads sources from
TO_DIR/datadirectory where the script writes transformed data to
DEBUGFALSEshould log messages be printed?
TOCED_INDEXTRUEshould index files (with table of content) be created if they do not exist and if they exist should a TOC be inserted?
TOC_ATTRS{"maxdepth":"3","hidden":""}JSON representation of dictionary with attributes for toctree inserted into index files⁠.

Special attributes:
  • .named (root level only) – if you want to define attributes at the dedicated path, you can put path/to/depth named dictionaries here.
  • .leveled (root level only) – you may define attributes by path depth level. TO_DIR defines level 0.
  • .prepend – define with any (also empty) value to prepend the index.rst file by TOC instead of append it.
Special attributes override general ones and .named one overrides .leveled ones. .named and .leveled have their root (level 0) in TO_DIR.

⁠example run command

Given an example data structure like that:

./md
 ├── amet.md
 ├── dolor
 │   ├── index.md
 │   └── sadipscing.md
 ├── lorem
 │   ├── index.md
 │   └── ipsum
 │       └── consetetur.md
 └── sit
     └── elitr.md
Click for bash code to generate this structure ... 
mkdir -p md/lorem/ipsum \
         md/dolor \
         md/sit

touch md/amet.md \
      md/lorem/index.md \
      md/lorem/ipsum/consetetur.md \
      md/dolor/sadipscing.md \
      md/sit/elitr.md

cat <<EOF > md/dolor/index.md
# Demo index

This index file is a first demonstration file.
EOF

cat <<EOF > md/lorem/index.md
# Demo index

This index file is a second demonstration file.
EOF

And running the docker image like that:

read -r -d '' TOCJSON <<- EOV
    {
        ".named": {
            "dolor": {
                ".prepend": ""
            },
            "lorem": {
                "maxdepth": "1"
            }
        },
        ".leveled": {
            "0": {
                "caption": "Table of contents",
                "maxdepth": "3",
                "hidden": ""
            }
        },
        "maxdepth": "3",
        "hidden": ""
    }
EOV

docker run --rm -t \
    -v $(pwd)/md:/dataMd   -e FROM_DIR="/dataMd" \
    -v $(pwd)/rst:/dataRst -e TO_DIR="/dataRst"  \
    -e TOC_ATTRS="${TOCJSON}" \
    macwinnie/md2rst:latest

Will result in this file structure:

./rst
 ├── amet.rst
 ├── index.rst
 ├── dolor
 │   ├── index.rst
 │   └── sadipscing.rst
 ├── lorem
 │   ├── index.rst
 │   └── ipsum
 │       ├── consetetur.rst
 │       └── index.rst
 └── sit
     ├── elitr.rst
     └── index.rst
Click to show generated index files ...
  • `rst/index.rst` 
    .. toctree::
   :caption: Table of contents
   :maxdepth: 3
   :hidden:

   amet
   dolor/index
   lorem/index
   sit/index
  • `rst/dolor/index.rst` 
    .. toctree::

   sadipscing

Demo index
==========

This index file is a first demonstration file.
  • `rst/lorem/index.rst` 
    
Demo index
==========

This index file is a second demonstration file.

.. toctree::
   :maxdepth: 1

   ipsum/index
  • `rst/lorem/ipsum/index.rst` 
    .. toctree::
   :maxdepth: 3
   :hidden:

   consetetur
  • `rst/sit/index.rst` 
    .. toctree::
   :maxdepth: 3
   :hidden:

   elitr

If you want to work with the directory levels in a range, you could use e.g. 1.. to define attributes for all levels greater or equal than 1 or 2..3 to define attributes to only be used at 2nd and 3rd levels.

Tag summary

Content type

Image

Digest

sha256:ef918cf09…

Size

403.4 MB

Last updated

3 days ago

docker pull macwinnie/md2rst