cjsheets / mkdocs-rtd-dropdown Goto Github PK

View Code? Open in Web Editor NEW

73.0 73.0 52.0 1.74 MB

MkDocs Theme - modified version of ReadTheDocs

Home Page: http://readthedocs.sheets.ch

License: MIT License

HTML 48.42% CSS 28.56% JavaScript 18.08% Python 2.79% Makefile 2.15%

mkdocs-rtd-dropdown's Introduction

ReadTheDocs Dropdown for MkDocs

A ReadTheDocs theme for MkDocs with collapsing menu support.

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.

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)

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
- See user-guide/instructions for an example

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.

mkdocs-rtd-dropdown's People

Contributors

Stargazers

Watchers

Forkers

stlehmann nazeim gabm guozhaoxia007 venkatsgit chenqing24 jonmalljw amitmund fuyukisakura joshua-roberts sunilheggodu masterstevelu lu-yi-hsun datadevx raulcastulo emmanuelmamed asiellb fanwenl lichenxinglcx lambros90 xingweitian marcadella charmingjune paco-portada daveadams1 ktrumanasi linxiaobo carolynkish300 yesyestoday2020 jmrh-ms ricky40403 gri-d guandaozhixing riddleandcode zachsirotto standardsoft ttanasart-pt mjrlegends ericgathuru machariaj atsuzaki kelvinoyugi kenyatek alexkyalo1 engineerombaty baodero biznapap babuviber tech2323 hrdkzala chenpaner

mkdocs-rtd-dropdown's Issues

mkdocs 1.0.1 via python 3.5 crash when attempting to use this variation of rtd theme

Theme does not seem to work with latest mkdocs that are installed from pip3.

site_name: My Docs
theme:
    name: 'rtd-dropdown'
  
pages:
    - Home: index.md

Requirement already up-to-date: mkdocs-rtd-dropdown in /usr/local/lib/python3.5/dist-packages (0.0.11)                                                                                                                 
Requirement already satisfied, skipping upgrade: mkdocs in /usr/local/lib/python3.5/dist-packages (from mkdocs-rtd-dropdown) (1.0.1)                                                                                   
Requirement already satisfied, skipping upgrade: Jinja2>=2.7.1 in /usr/local/lib/python3.5/dist-packages (from mkdocs->mkdocs-rtd-dropdown) (2.10)                                                                     
Requirement already satisfied, skipping upgrade: PyYAML>=3.10 in /usr/local/lib/python3.5/dist-packages (from mkdocs->mkdocs-rtd-dropdown) (3.13)                                                                      
Requirement already satisfied, skipping upgrade: livereload>=2.5.1 in /usr/local/lib/python3.5/dist-packages (from mkdocs->mkdocs-rtd-dropdown) (2.5.2)                                                                
Requirement already satisfied, skipping upgrade: click>=3.3 in /usr/local/lib/python3.5/dist-packages (from mkdocs->mkdocs-rtd-dropdown) (6.7)                                                                         
Requirement already satisfied, skipping upgrade: Markdown>=2.3.1 in /usr/local/lib/python3.5/dist-packages (from mkdocs->mkdocs-rtd-dropdown) (2.6.11)                                                                 
Requirement already satisfied, skipping upgrade: tornado>=5.0 in /usr/local/lib/python3.5/dist-packages (from mkdocs->mkdocs-rtd-dropdown) (5.1)                                                                       
Requirement already satisfied, skipping upgrade: MarkupSafe>=0.23 in /usr/local/lib/python3.5/dist-packages (from Jinja2>=2.7.1->mkdocs->mkdocs-rtd-dropdown) (1.0)                                                    
Requirement already satisfied, skipping upgrade: six in /usr/lib/python3/dist-packages (from livereload>=2.5.1->mkdocs->mkdocs-rtd-dropdown) (1.10.0)

krisjanis@HAL-3000:~/Data/Temp/docs.test/derp$ mkdocs serve                                                                                                                                                            
INFO    -  Building documentation...                                                                                                                                                                                   
INFO    -  Cleaning site directory                                                                                                                                                                                     
Traceback (most recent call last):                                                                                                                                                                                     
  File "/usr/local/bin/mkdocs", line 11, in <module>                                                                                                                                                                   
    sys.exit(cli())                                                                                                                                                                                                    
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 722, in __call__                                                                                                                                   
    return self.main(*args, **kwargs)                                                                                                                                                                                  
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 697, in main                                                                                                                                       
    rv = self.invoke(ctx)                                                                                                                                                                                              
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 1066, in invoke                                                                                                                                    
    return _process_result(sub_ctx.command.invoke(sub_ctx))                                                                                                                                                            
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 895, in invoke                                                                                                                                     
    return ctx.invoke(self.callback, **ctx.params)                                                                                                                                                                     
  File "/usr/local/lib/python3.5/dist-packages/click/core.py", line 535, in invoke                                                                                                                                     
    return callback(*args, **kwargs)                                                                                                                                                                                   
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/__main__.py", line 134, in serve_command                                                                                                                         
    livereload=livereload                                                                                                                                                                                              
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/serve.py", line 119, in serve                                                                                                                           
    config = builder()                                                                                                                                                                                                 
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/serve.py", line 114, in builder                                                                                                                         
    build(config, live_server=live_server, dirty=dirty)                                                                                                                                                                
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/build.py", line 285, in build                                                                                                                           
    _build_theme_template(template, env, files, config, nav)                                                                                                                                                           
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/build.py", line 114, in _build_theme_template                                                                                                           
    output = _build_template(template_name, template, files, config, nav)                                                                                                                                              
  File "/usr/local/lib/python3.5/dist-packages/mkdocs/commands/build.py", line 93, in _build_template                                                                                                                  
    output = template.render(context)                                                                                                                                                                                  
  File "/usr/local/lib/python3.5/dist-packages/jinja2/environment.py", line 1008, in render                                                                                                                            
    return self.environment.handle_exception(exc_info, True)                                                                                                                                                           
  File "/usr/local/lib/python3.5/dist-packages/jinja2/environment.py", line 780, in handle_exception                                                                                                                   
    reraise(exc_type, exc_value, tb)
  File "/usr/local/lib/python3.5/dist-packages/jinja2/_compat.py", line 37, in reraise
    raise value.with_traceback(tb)
  File "/usr/local/lib/python3.5/dist-packages/rtd_dropdown/search.html", line 1, in top-level template code
    {% extends "base.html" %}
  File "/usr/local/lib/python3.5/dist-packages/rtd_dropdown/base.html", line 78, in top-level template code
    {%- block site_nav %}
  File "/usr/local/lib/python3.5/dist-packages/rtd_dropdown/base.html", line 79, in block "site_nav"
    {% include 'nav.html' %}
  File "/usr/local/lib/python3.5/dist-packages/rtd_dropdown/nav.html", line 11, in top-level template code
    {%- if nav_item_children[0].input_path is defined %}
  File "/usr/local/lib/python3.5/dist-packages/jinja2/environment.py", line 430, in getattr
    return getattr(obj, attribute)
jinja2.exceptions.UndefinedError: None has no element 0

Errror when installed.

Delete this. Accident Issue

pip install can't find 'requirements.txt'

Using python 3.5.x from anaconda. I get the following:

(mkdocs-environment) BusterBoy:wellzesta-docs jmr$ pip install mkdocs-rtd-dropdown
Collecting mkdocs-rtd-dropdown
  Using cached mkdocs-rtd-dropdown-0.0.9.tar.gz
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/private/var/folders/g_/xb36_7gn2zg21qz3_rlt6k9w0000gp/T/pip-build-mviy3t01/mkdocs-rtd-dropdown/setup.py", line 5, in <module>
        with open("requirements.txt") as data:
    FileNotFoundError: [Errno 2] No such file or directory: 'requirements.txt'
    
    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /private/var/folders/g_/xb36_7gn2zg21qz3_rlt6k9w0000gp/T/pip-build-mviy3t01/mkdocs-rtd-dropdown/

del

More collapsing levels required for current project documentation

Hello! Thanks for the theme which gives support for the outlines sidebar, it almost solved all my documentation demands. The problem I'm facing right now is I need more than 6 collapsing levels for current project, this is how my documentation layer looks like:

"#Admin-User"
"## Header Navigation"
"###Clients"
"#### Overview"
"#### Function Describe"
"##### Address"
"##### User Info"
"###### Edit"
"####### Save"
...
"##### Account Info"
...
"## Tap Bar Menu"
...

As you see, "####### Save" is already more than 6 collapsing levels and it will display like "# Save". If there is any chance you can add more collapsing levels like 8 or more, that will helps a lot from my side.

Theme not found despite successful installation

~/Data/NodeMCU/nodemcu-firmware (dev) > pip --no-cache-dir install mkdocs-rtd-dropdown
Collecting mkdocs-rtd-dropdown
  Downloading mkdocs_rtd_dropdown-0.0.6-py2-none-any.whl (362kB)
    100% |################################| 368kB 4.6MB/s 
Requirement already satisfied: mkdocs in /usr/local/lib/python2.7/site-packages (from mkdocs-rtd-dropdown)
Requirement already satisfied: PyYAML>=3.10 in /usr/local/lib/python2.7/site-packages (from mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: click>=3.3 in /usr/local/lib/python2.7/site-packages (from mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: Markdown>=2.3.1 in /usr/local/lib/python2.7/site-packages (from mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: livereload>=2.5.1 in /usr/local/lib/python2.7/site-packages (from mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: tornado>=4.1 in /usr/local/lib/python2.7/site-packages (from mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: Jinja2>=2.7.1 in /usr/local/lib/python2.7/site-packages (from mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: six in /usr/local/lib/python2.7/site-packages (from livereload>=2.5.1->mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: backports-abc>=0.4 in /usr/local/lib/python2.7/site-packages (from tornado>=4.1->mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: singledispatch in /usr/local/lib/python2.7/site-packages (from tornado>=4.1->mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: certifi in /usr/local/lib/python2.7/site-packages (from tornado>=4.1->mkdocs->mkdocs-rtd-dropdown)
Requirement already satisfied: MarkupSafe in /usr/local/lib/python2.7/site-packages (from Jinja2>=2.7.1->mkdocs->mkdocs-rtd-dropdown)
Installing collected packages: mkdocs-rtd-dropdown
Successfully installed mkdocs-rtd-dropdown-0.0.6
~/Data/NodeMCU/nodemcu-firmware (dev) > mkdocs serve
INFO    -  Building documentation... 
ERROR   -  Config value: 'theme'. Error: Unrecognised theme name: 'rtd-dropdown'. The available installed themes are: readthedocs, mkdocs 

Aborted with 1 Configuration Errors!
~/Data/NodeMCU/nodemcu-firmware (dev) > mkdocs --version
mkdocs, version 0.17.1
~/Data/NodeMCU/nodemcu-firmware (dev) > pip --version
pip 9.0.1 from /usr/local/lib/python2.7/site-packages (python 2.7)
~/Data/NodeMCU/nodemcu-firmware (dev) > python --version
Python 2.7.10

Fenced code blocks rendered as single line

I seem unable to show more than a single line at a time in preformatted fenced code blocks.

Mark up written like this:
```
line 1
line 2
```
Will always be rendered in HTML like this:

line 1 line 2

Having a play around, it seems that it's because the white-space CSS property for <code> is set to "nowrap", but even disabling that, newlines in the original markup seem to have been ignored.

Sidebar totally garbled with lots of pages

The theme fails to handle the documentation for https://github.com/nodemcu/nodemcu-firmware/. The sidebar is nearly empty when there should be lots of content. I turned off our js/extra.js to test but the behavior is the same.

yml parameter for foldes states by default

Right now when I open link, it open all submenus unfolded. I would like to keem them folded and user will unfold what he wants.

Can you add an option for yml config?

loss some fonts

hi,i like this theme very much.But i updated the mkdocs and mkdocs-rtd-dropdown.loss some fonts

is theme: rtd-dropdown the same as theme: readthedocs

hello there, I'm just starting out and i could not find this information in internet search.

Is the "rtd-dropdown" theme the same or an alias to adding "readthedocs" (one of the default names allowed/included in mkdocs).

theme: readthedocs

My friend Ralim has theme: readthedocs in his mkdoc.yml and it seems to have all the collapsible menu functions as shown in this repo for "rtd-dropdown". I'm wondering if they are identical or if we should switch to "rtd-dropdown" for additional functionality.

webpage: https://ralim.github.io/IronOS/
yml file is here: https://github.com/Ralim/IronOS

codeblock highlight error

i am very like rtd-dropdown this theme，but there is a error 。

this is rtd-dropdown

this is readthedocs

hopeful you can fix 。 thanks

Code Fences not being displayed properly

Dear Developers,

Unfortunately the code fences are not working properly with the actual version. They are being displayed, however, new lines are not recognized. Everything is being displayed into one single line, could you please have a look at it ?

Kind Regards,
Cristian

sidebar styling issue

Hello!
First off, thank you for continuing to develop this theme for mkdocs! I am running into an issue where the sidebar styling gets messy with overlapping elements. Doesn't seem to matter if using nav configuration or not in the mkdocs.yml. I've listed my mkdocs.yml file below as well as a screenshot of the issue. Noticed this happens with both the mkdocs serve & build commands.

#example mkdocs.yml
site_name: Test Docs

nav:
  - Home: 'index.md'

theme:
  name: rtd-dropdown

python: 2.7.15rc1
mkdocs: 1.0.4
mkdocs-rtd-dropdown: 1.0.2

Any thoughts or insights into what's causing this would be greatly appreciated! I'd be happy to provide any further information if needed. Thank you in advance!

Overlayed expand boxes

First of all: Thanks for this nice theme and the work you put into it.

I just discovered that the expand boxes in the sidebars are overlayed by the following text.

I fixed this by adjusting the padding and will send a PR (#8 ) for it.

Extra title in navigation

I think I missed repository by creating that issue

mkdocs/mkdocs#1374

I think this one is few seconds for you to fix and I'd referred to your template.

Navigation link busted (for me) - fix included

site.xml would have correct links, but in index.html there would be a / added to the relative link. This would break the navigation.

Here is a reproducible example:
repo
pages

The fix is to change nav.html file (in my anaconda this is /home/kris/anaconda3/lib/python3.6/site-packages/rtd_dropdown/nav.html) and replace the line {%- set child_url = nav_item.abs_url %} with {%- set child_url = nav_item.url %}.

Leaving this here just in case anybody else wants a fix.

Otherwise, thanks for the theme, I really like that functionality (collapsible menus).

broken links

broken links in Readme

Show children for all root nodes

I propose to add child nav items not only to the currently selected root item but also to all others. Here is the reason:

If you use directories to structure your project they will be visible inside the navigation. However it is not possible to make them active because they are not connected to a Markdown document. That is why the children of these directories will never be visible in the toc.

this plugin can collapse for each page with its heading sections, but not for all the pages under the folder name when you click on the folder name.

say, i have:

docs/folder1/file1.md
docs/folder1/file2.md

if I can click on "folder1" it will collapse that will be great.