#directory-structure #mdbook #preprocessor #folder #markdown #render #markdowns

bin+lib mdbook-all-the-markdowns

Render all markdown files in a given folder structure

2 unstable releases

0.3.0 Nov 10, 2021
0.2.0 Nov 1, 2021

#75 in #directory-structure

MIT license

255KB
361 lines

All the markdowns
All The Markdowns!

This is a mdbook preprocessor that will walk a specified base path and add all the markdowns to your mdbook. This is pretty naive and will probably work best for smaller projects but feel free to give it a go for any folder structure!

Configuration

The preprocessor can be configured with the following settings:

[preprocessor.all-the-markdowns]
# This will mark all folders generated for a proper index as draft, making them
# non clickable. By default this is false and the content will just be the name
# of the folder as title.
draft-folders = true

[[preprocessor.all-the-markdowns.section]]
# The title to use in the index on the left. Can be useful if book also consist
# of static content or if creating multiple sections.
title = "Auto generated"

# The base directory to find markdowns in, this is usually the root of your
# project if you're only creating a single section.
base = "./examples/example-folder-structures/slim"

# Paths to ignore. No matter where you set your base you can always ignore given
# patterns. These needs to be relative to the base since the directory traverser
# will match if a file or director _starts with_ any of these patterns.
ignore = []

Since section is a list of tables you can add multiple groups by adding multiple sections.

[preprocessor.all-the-markdowns]

[[preprocessor.all-the-markdowns.section]]
title = "Libraries"
base = "./examples/example-folder-structures/slim/my-libraries"
ignore = []

[[preprocessor.all-the-markdowns.section]]
title = "Services"
base = "./examples/example-folder-structures/slim/my-services"
ignore = []

Example

Given the following folder structure:

.
├── my-libraries
   └── lib-biz
       ├── INSTALLATION.md
       ├── README.md
       ├── sub-lib-a
       │   ├── CONTRIBUTORS.md
       │   ├── README.md
       │   └── USAGE.md
       └── sub-lib-b
           └── README.md
└── my-services
    ├── service-bar
       ├── README.md
       └── infra
           └── kubernetes
               └── README.md
    └── service-foo
        └── README.md

Based on the title in each document, combined with the folder names as title case, the preprocessor with the first configuration would render the following:

Result with the first example with one section. Result with the second example with multiple sections.

Test

You can test rendering any of the example folders in this directory with the book found in examples/book1 with mdbook serve examples/book1.

Dependencies

~13–25MB
~368K SLoC