chrissimpkins / cinder Goto Github PK
View Code? Open in Web Editor NEWA clean, responsive MkDocs theme
Home Page: http://sourcefoundry.org/cinder/
License: Other
A clean, responsive MkDocs theme
Home Page: http://sourcefoundry.org/cinder/
License: Other
Not exactly sure why but the 404.html file is not generated in site_dir
when running mkdocs build
. Even when it is generated (using static_template
and by-passing an error), it contains broken links.
I could probably address the problem in a PR. Let me know.
Found two issues that seem to stem from incomplete MkDocs >=0.17 support.
Running mkdocs serve
yields:
WARNING - The theme 'cinder' does not appear to have a configuration file. Please upgrade to a current version of the theme.
-> https://github.com/mkdocs/mkdocs/blob/master/docs/about/release-notes.md#theme-customization-1164
And then later when browsing the docs:
404 GET /mkdocs/js/require.js (127.0.0.1)
-> likely this: https://github.com/mkdocs/mkdocs/blob/master/docs/about/release-notes.md#plugin-api-206
The side bar collapses in the main text when zooming out (Safari macOS): mkdocs/mkdocs#1050
how would one go around making a drop-down folder?
When running mkdocs serve locally I get the following (desirable) result:
But when I build my site using mkdocs build I get the following (undesirable) result:
In the second example, the font is different and when I move between pages, the whole page "glitches". It seems that the fonts are correct for about 0.5 seconds and then it turns into the thinner font. Also, the icons disappear in the build version.
I've tested this in both Firefox and Chrome, on two different computers.
Hi
I noticed today that syntax highlighting does not work for me. I have tried various things, but I only get syntax highlighting back if I disable Cinder
:(
I have made a repository that shows my setup, but the gist is this:
pip install mkdocs && pip install mkdocs-cinder
mkdocs.yml
(see below)site_name: Syntax highlighting issue
theme:
name: cinder
docs_dir: src
If I comment out the theme
block in the config, then highlighting works.
Any help would be greatly appreciated.
While working on a very large document, the sidenav ToC can be quite unwieldy where it will flow past the viewport with no way to scroll to access the remaining links, for instance:
Might be hard to see, but at the bottom, the edge of the browser window shows that there is more content beneath.
A solution to this would be to collapse the items when they're not active, much like how the right-nav items on the bootstrap docs do. Here's what it would look like in that case:
I've already written most of the code to do this and I think I can come up with a way to "enable" it via CSS. I'm more curious if this is a desired feature or not. I'd love to see it there as I plan to use this for this internal project's documentation, but those docs are quite lengthy, so I'm running into this problem often.
Let me know if you want this and I'll make a PR.
Google Chrome
Version 65.0.3325.181
We are based on v3 and v4 is out. Anyone want to take a crack at an update?
Hi @chrissimpkins , http://sourcefoundry.org/cinder/specimen/ looks great,
wonder could you please add some example .md that enables fontawesome icons and bootstrap buttons?
thanks!
When clicking the search button, the focus should be on the search box so users could type immediately without clicking again on that box.
Just installed cinder and got the following warnings when building my documentation.
WARNING - Template variable warning: 'page_description' is being deprecated and will not be available in a future version. Use 'config.site_description' instead.
WARNING - Template variable warning: 'site_author' is being deprecated and will not be available in a future version. Use 'config.site_author' instead.
WARNING - Template variable warning: 'canonical_url' is being deprecated and will not be available in a future version. Use 'page.canonical_url' instead.
WARNING - Template variable warning: 'favicon' is being deprecated and will not be available in a future version. Use '{{ base_url }}/img/favicon.ico' instead.
WARNING - Template variable warning: 'page_title' is being deprecated and will not be available in a future version. Use 'page.title' instead.
WARNING - Template variable warning: 'site_name' is being deprecated and will not be available in a future version. Use 'config.site_name' instead.
WARNING - Template variable warning: 'google_analytics' is being deprecated and will not be available in a future version. Use 'config.google_analytics' instead.
WARNING - Template variable warning: 'current_page' is being deprecated and will not be available in a future version. Use 'page' instead.
WARNING - Template variable warning: 'copyright' is being deprecated and will not be available in a future version. Use 'config.copyright' instead.
WARNING - Template variable warning: 'include_nav' is being deprecated and will not be available in a future version. Use 'nav|length>1' instead.
WARNING - Template variable warning: 'include_next_prev' is being deprecated and will not be available in a future version. Use '(page.next_page or page.previous_page)' instead.
WARNING - Template variable warning: 'repo_url' is being deprecated and will not be available in a future version. Use 'config.repo_url' instead.
WARNING - Template variable warning: 'homepage_url' is being deprecated and will not be available in a future version. Use 'nav.homepage.url' instead.
WARNING - Template variable warning: 'previous_page' is being deprecated and will not be available in a future version. Use 'page.previous_page' instead.
WARNING - Template variable warning: 'next_page' is being deprecated and will not be available in a future version. Use 'page.next_page' instead.
WARNING - Template variable warning: 'repo_name' is being deprecated and will not be available in a future version. Use 'config.repo_name' instead.
WARNING - Your theme does not appear to contain a 'main.html' template. The 'base.html' template was used instead, which is deprecated. Update your theme so that the primary entry point is 'main.html'.
WARNING - Template variable warning: 'toc' is being deprecated and will not be available in a future version. Use 'page.toc' instead.
WARNING - Template variable warning: 'meta' is being deprecated and will not be available in a future version. Use 'page.meta' instead.
WARNING - Template variable warning: 'content' is being deprecated and will not be available in a future version. Use 'page.content' instead.
@chrissimpkins - I have completed this locally - happy to cut a PR if you're open to it. I've tested and things are working well. There's some documentation updates we should include as well - can add those to my PR as well.
Hello,
I installed mkdocs and cinder via choco/pip.
My settings:
site_name: Example
theme: cinder
nav:
- Home: index.md
- Features:
- 'Create an account': 'features/create-an-account.md'
When I click on 'Features' on the top menu, this error shows in my browser's console.
Error: Syntax error, unrecognized expression: #
The nav bar works fine using the default theme for mkdocs.
Thank you.
Hey, really love the theme. I created some documentation for my work today and now have the problem that it takes up to a minute to load the external resources and display the site in internet explorer. i guess our corporate av/ids takes forever checking the js code before finally letting me load. Any chance to change the source to make it possible to selfhost the needed js/font files?
I was reading https://www.mkdocs.org/user-guide/styling-your-docs/#mkdocs and looking at the part about shortcuts.
Using the Cinder theme, I wanted to change the next/previous shortcuts to the arrow keys. Here's what I put in my mkdocs.yml
.
theme:
name: null
custom_dir: 'custom/themes/cinder/cinder'
shortcuts:
next: 39
previous: 37
The left and right arrow keys did not trigger next/previous.
I tried removing the shortcuts
so my mkdocs.yml
looks like this....
theme:
name: null
custom_dir: 'custom/themes/cinder/cinder'
The mkdocs docs say that the default shortcuts are the n
and p
keys.
However, the n
and p
keys don't do anything either. I tried starting stopping mkdocs serve
and still no dice.
Are shortcuts supposed to work with Cinder? Am I doing something wrong here?
this theme is really cool and much better than the mkdocs default one!
One issue would be very nice to address is to support more than a 2nd level of navigation. Actually current mkdcos/readthedocs theme actually already support it. Could we make it working with Cinder?
I tried it does not work at this point. Thanks!!
https://www.bountysource.com/issues/2321017-allow-nav-links-with-depth-2
https://groups.google.com/forum/m/#!msg/mkdocs/rU73ZC1BKis/L9C513KVd3sJ
I'm not sure where this problem lies but highlight JS is not correctly syntax highlighting some code. There is an example here: http://jackmitch.github.io/libsoc/c/gpio#libsoc_gpio_request
If you compare libsoc_gpio_request to libsoc_gpio_free there are two different styles used. However they are declared the same way in the doc files: https://raw.githubusercontent.com/jackmitch/libsoc/master/static-docs/docs/c/gpio.md
I couldnt find what version of highlight js is used in the theme, so maybe it just needs updating?
Hi Chris,
I do like your theme, great work !
But I do have an issue with png images.
If I use the default mkdocs theme and I view my documentation on a small screen or if I make a desktop window smaller, the images do get smaller and the font stays the same size. This way the document stay readable.
With the cinder theme, png images do not get smaller on desktop, but I do get a scrollbar.
On an iPhone the images fits the screen, but then the font get so small, that it is unreadable.
(I have attached screenshots to show the problem.)
It does not make a difference if I use markdown syntax or html syntax for displaying the image.
If I use svg vector images, the images scale as expected and everything works fine.
(I have not tried jpeg images.)
Do you have any idea about what is happening ?
Thanks for your help,
Thomas
@jeffpeiyt : I saw your comment on the MkDocs repository (mkdocs/mkdocs#756).
We can work on support for this if you are still interested.
I followed the steps on https://sourcefoundry.org/cinder/ but when I try to serve, I get an error ...
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
ERROR - Error building page 'index.md': main.html
Traceback (most recent call last):
File "/home/user/.local/bin/mkdocs", line 8, in <module>
sys.exit(cli())
File "/home/user/.local/lib/python3.8/site-packages/click/core.py", line 1130, in __call__
return self.main(*args, **kwargs)
File "/home/user/.local/lib/python3.8/site-packages/click/core.py", line 1055, in main
rv = self.invoke(ctx)
File "/home/user/.local/lib/python3.8/site-packages/click/core.py", line 1657, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/home/user/.local/lib/python3.8/site-packages/click/core.py", line 1404, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/home/user/.local/lib/python3.8/site-packages/click/core.py", line 760, in invoke
return __callback(*args, **kwargs)
File "/home/user/.local/lib/python3.8/site-packages/mkdocs/__main__.py", line 181, in serve_command
serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
File "/home/user/.local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 63, in serve
config = builder()
File "/home/user/.local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 58, in builder
build(config, live_server=live_server, dirty=dirty)
File "/home/user/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 314, in build
_build_page(file.page, config, doc_files, nav, env, dirty)
File "/home/user/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 209, in _build_page
template = env.get_template('main.html')
File "/home/user/.local/lib/python3.8/site-packages/jinja2/environment.py", line 1000, in get_template
return self._load_template(name, globals)
File "/home/user/.local/lib/python3.8/site-packages/jinja2/environment.py", line 959, in _load_template
template = self.loader.load(self, name, self.make_globals(globals))
File "/home/user/.local/lib/python3.8/site-packages/jinja2/loaders.py", line 126, in load
source, filename, uptodate = self.get_source(environment, name)
File "/home/user/.local/lib/python3.8/site-packages/jinja2/loaders.py", line 218, in get_source
raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: main.html
The footer block code should include the revision statement so that it can be overridden in a main.html file if wanted.
{% block footer %}
<hr>
<p>{% if config.copyright %}
<small>{{ config.copyright }}<br></small>
{% endif %}
<small>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p></small>
{% endblock %}
{% if page.meta.revision_date %}<br>
<small>Revised on: {{ page.meta.revision_date }}</small>
{% endif %}
Change to:
{% block footer %}
<hr>
<p>{% if config.copyright %}
<small>{{ config.copyright }}<br></small>
{% endif %}
<small>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p></small>
{% if page.meta.revision_date %}<br>
<small>Revised on: {{ page.meta.revision_date }}</small>
{% endif %}
{% endblock %}
If there is a long page with 20 + headings then the sidebar does not scroll into view when page scrolls so the bottom items are permanently hidden.
You can see in the attached image I am on the bottom section but there is still loads more content that I can scroll (see scrollbar) but the menu does not scroll with the content.
Similar to #10, except I'd like to switch the Previous/Next buttons off, as my docs aren't strictly linear.
Would you accept a pull request that allows for this (and #10 while I'm there, I guess)? I would probably do something similar to how mkdocs-material does this, and add the options under the theme
key.
Edit: and possibly an additional option to disable the footer. I'd really like to be able to drop Cinder into my projects with just a mkdocs.yml
and have nothing else to override
Is the index.md feature supported as described here?
I have this problem
File "/Users/Kato/anaconda/lib/python2.7/site-packages/cinder/nav.html", line 18, in template
<a class="navbar-brand" href="{{ nav.homepage.url|url }}">{{ config.site_name }}</a>
jinja2.exceptions.TemplateAssertionError: no filter named 'url'
markdown_extensions:
- toc:
# permalink: True # renders ¶ sign
permalink: '#'
Renders permalinks next to h
elements but they're static-always-on. The more common behavior found around the internet is they're only displayed on hover.
Inspiriation:
Add support for all 90+ color schemes that are released by highlightjs.
Hi, loving the theme, but when I built the site locally, and access it from file explorer, it takes 30 seconds + to load. I have commented out highlight js and google fonts in base.html, but it still seems to take a very long time to load locally.
With the release of MkDocs 0.15 it would be great to have this uploaded to PyPI so users can easily pip install it. The documentation for doing this can be doing here:
http://www.mkdocs.org/user-guide/custom-themes/#packaging-themes
This is a new feature and the documentation probably not totally great yet, so let me know if I can help!
add the [copyright: "Cinder is licensed under the MIT license"] in mkdocs.yml,
but no effect.
Hi,
Would it be possible to introduce a new theme setting to disable the highlight.js extension ?
This is a much-needed feature as highlight.js may conflict with other JS scripts, such as the mermaid drawing engine which I use heavily. So far, this conflict prevents me from using cinder on my mkdocs instances.
Thanks!
It would be nice to have a dark variant of this theme. At the moment browser plugins like DarkReader cannot achieve to render the whole theme correctly.
What do you think?
Hiya
Is there a way to order the pages and folders in the sub menu's
I have my pages and folders numbered 1.1 1.2 1.3 etc
but at the moment its putting the pages first, then folders at the end
so my menu looks
1.1 - page
1.4 - page
1.2 - Folder
1.3 - Folder
Im not sure if its a theme problem or a mkdocs problem
I tried to make a custom nav in the yml but when I put it in, the menu disappears entirely from the theme?
Thanks
The link in line 36 of base.html (https://ajax.googleapis.com/ajax/libs/webfont/1.6.28/webfont.js) is not available on Google CDN. It returns a 404. It seems the latest version supported/published is 1.6.26 (see here) even though 1.6.28 is the latest release for Web Font Loader.
Also, not sure if this library is needed. Fonts are explicitly downloaded, see lines 19 and 20.
cinder
package name is used by Openstack Cinder module.
Can you refactor package name to mkdocs-cinder or other name ?
So, users could be have at same time both packages.
Thanks in advance
Essentially a duplicate of mkdocs/mkdocs#779. Fix detailed here:
I want to create homepage with md-12 but I am not able to find out where to define disable_toc parameter ?
<div class="container">
{% block content %}
{% if page.meta.disable_toc %}
<div class="col-md-12" role="main">{% include "content.html" %}</div>
{% else %}
<div class="col-md-4">{% include "toc.html" %}</div>
<div class="col-md-8" role="main">{% include "content.html" %}</div>
{% endif %}
{% endblock %}
</div>
If anyone faced with same problem please can help me ?
Hi,
I'm using Cinder in these two projects:
The "Edit on Github" button (on the right top corner) is pointing to the edit URL using the "master" branch.
I think the config file is OK:
site_name: Secure Git Guide
site_url: https://github.com/Nautilus-Cyberneering/secure-git-guide
repo_url: https://github.com/Nautilus-Cyberneering/secure-git-guide
site_description: "A collections of articles about Git, GitHub and GPG focused on security"
nav:
- Home: index.md
theme:
name: null
custom_dir: "cinder"
I've even tried to use the "edit_url" config option but it does not work.
I'm using:
thank you for this theme , I come from china. i should write chinses document. but i find it do not support Chinese search. only english.
so, can you do further optimization.
thanks very much!
It seems like Cinder is generating invalid sitemaps:
e.g. https://sourcefoundry.org/cinder/sitemap.xml
I'm seeing this on our docs site too but not on the MkDocs site:
Hi there,
Can you add a yml variable like 'include_search' so we can toggle the search in the navigation bar on and off? I've added this to my local copy of Cinder with the following {% include_search %}/{% endif %} in nav.html
{% if include_search %}
<li>
<a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
{% endif %}
Thanks for the wonderful theme. I normally tweak Jekyll for larger sites and wanted to use mkdocs/cinder for a very small (3-4 page) site. Cinder is great out of the box. Thanks.
Hello,
Thanks to everyone who has put time and thought into making and sharing this.
I found that if you have a slightly long site name and several top-level navigation items, the top of the navigation sidebar is cut off:
Here I just used the base install download, only change is site name and items.
Screencap is Firefox 86 on Mac. Tried in Safari 13 and same effect though it took a wee bit more.
I think it occurs when site name and navigation take 2 lines instead of 1.
Workaround: A few sequential empty ##
at top of file pushes links down. Scrollbar still cut off of course, giving impression that something might be just out of view.
I am not sure if I have some extremely unusual usecase or what. Couldn't find this in previous issues though did find #24 and related.
It seems that mkdocs_theme.yml
cannot be empty for mkdoc 1.0. When run mkdocs serve
, I got Traceback as follows:
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 107, in builder
site_dir=site_dir
File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/base.py", line 197, in load_config
errors, warnings = cfg.validate()
File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/base.py", line 115, in validate
post_failed, post_warnings = self._post_validate()
File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/base.py", line 95, in _post_validate
config_option.post_validation(self, key_name=key)
File "/usr/local/lib/python3.5/dist-packages/mkdocs/config/config_options.py", line 432, in post_validation
config[key_name] = theme.Theme(**theme_config)
File "/usr/local/lib/python3.5/dist-packages/mkdocs/theme.py", line 47, in __init__
self._load_theme_config(name)
File "/usr/local/lib/python3.5/dist-packages/mkdocs/theme.py", line 96, in _load_theme_config
parent_theme = theme_config.pop('extends', None)
AttributeError: 'NoneType' object has no attribute 'pop'
Just fill the file with some content followed the grammer of yaml resolved this issue.
My Python version is 3.5.2.
Would be helpful if you added support for
markdown_extensions:
- admonition: #http://pythonhosted.org/Markdown/extensions/admonition.html
Inspiration:
I'm new to mkdocs, so maybe the problem is obvious, but has the name of the theme changed? I created a virtual environment to test the mkdocs-cinder
package.
I installed it with pip install mkdocs-cinder
and created a new mkdocs project with mkdocs new
. My mkdocs.yml
file is as simple as it gets
site_name: My Docs
theme: cinder
but when build the project I get the error
ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'cinder'. The available installed themes are: mkdocs, readthedocs
Aborted with 1 Configuration Errors!
pip list
shows that the package is installed
Package Version
------------- -------
mkdocs-cinder 1.0.4
but it can't find the theme for some reason.
If you have a document of substantial length with a lot of code blocks, Scrollspy will fall out of sync as HighlightJS does its stuff after Scrollspy has been applied.
For an example, I clicked on the .tugboat/app.json
link in the sidenav, and you can see that it's not correctly lining up the content with the navigation.
The fix is simple and I'll attach a PR with it.
It could be useful to pop the search box when someone starts typing. Currently, AFAIK, there are no other events that listen to the keyboard key down so it should be feasible.
I'm trying to generate a offline documentation for a API.
If I open the index.html
file directly I get the following errors:
Screenshots:
Network:
The problem is that urls starting with //
will be blocked by the browser for security reasons.
https:
to all external urlsOR
css/
and js/
directory and change the href. This would be better for offline browsing.Not 100% sure if I'm doing something wrong or not (I do see highlightjs 9.13 is installed/being used), but I can't seem to get other languages than the default 23 to work.
Specifically, I'm trying with Mikrotik RouterOS highlights (for configuration documentation).
Setting
hljs_languages:
- routeros
doesn't change the highlight to the correct highlight (you can see readthedocs for an example, it works there)
Is there an easy way I can add the stylesheet in to support it? I also tried setting a custom stylesheet with extra_css
but that didn't seem to do anything either.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.