MkDocs Theme - modified version of ReadTheDocs
Clone or download
Latest commit 5e8a456 Aug 20, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs fix first-level themes Aug 20, 2018
rtd_dropdown remove debug statements Aug 20, 2018
.gitignore dash to underscore Oct 31, 2017
.travis.yml add travis file Mar 12, 2018
LICENSE add requirements as package dependency Mar 18, 2018
MANIFEST.in add requirements as package dependency Mar 18, 2018
Makefile update mkdocs theme Nov 5, 2017
README.md update version and pacakge Aug 20, 2018
mkdocs.yml set default theme name Aug 20, 2018
requirements.txt update version and pacakge Aug 20, 2018
setup.py version bump Aug 20, 2018

README.md

ReadTheDocs Dropdown for MkDocs

Pypi Version

A ReadTheDocs theme for MkDocs with collapsing menu support.

Dropdown Demo

How to install

Install the ReadTheDocs Dropdown theme with pip:

pip install mkdocs-rtd-dropdown

Set the theme name to rtd-dropdown in your projects mkdocs.yml:

theme:
  name: 'rtd-dropdown'

How to use

See the supplied docs folder as an example. The main limitation is each file name needs to be the same as the first heading in each file. This seems to be a fairly common configuration.

MkDocs added navigation improvemetns which allows this theme to support more than 2 collapsing levels.

The stylesheets are currently only configured for 4 levels. Please reaise an issue if you need style support for more than that.

How to use (Old Version, pre-v1.0)

Similar to readthedocs.io, this theme is built assuming a flat file structure.

File Structure (Old Version, pre-v1.0)

Right now, your documentation can only use the first two file levels. I'm working on adding support for a 3rd level.

Code structure

In the example above, MkDocs will be a linked-page on the sidebar (to index.md) while UserGuide will be a category containing the pages nested under it (ex. Instructions which contains instructions.md)

Code output

Note: If you don't declare your doc-structure explicitly in mkdocs.yml, each folder is considered a file level.

Collapsing

The dropdown menu is controlled by heading levels.

# Page Title    <-- H1

content, content, content

## Section      <-- H2

### Section     <-- H3

The rules for headings are essentially:

  • If there is only one H1, it will be ignored and the page/file name will be the root dropdown element
    • Having 2 sub-menus with no choices was a wierd experience
    • See MkDocs for an example
  • If there are multiple H1, they each become dropdown elements

There is currently no support for H3+ dropdowns. I'm working on adding support to the next version.

Considerations

  • Based on the ReadTheDocs theme build-into MkDocs
  • Adds dropdown functionality to the sidebar (similar to ReadTheDocs)

For further discussion, see this issue.

Development

If you discover bugs or areas for improvement please feel free to submit issues or PRs.

Analytics