Comments (6)
why is the home page not at the outermost level? how do you navigate to an outer level from an inner one?
That is bothering me too. I didn't take time yet to look for a solution.
Regarding navigation, I find it hard to navigate within the Nature theme, mainly because the left sidebar doesn't show the pages, but only the headings in the current page, and the "next topic". As you mentioned, there's the index link at the top right, but it's not easy to spot, and having to click on index every time you want to see what other pages are available does not help navigation. This could be fixed by showing the index link more prominently, or actually showing pages in the sidebar (maybe not all pages, just the ones at the same level).
from markdown.
I will state the lack of search is a bug that was introduced very recently. I've created a bug with the identified cause. #1416
from markdown.
Opened a PR #1413
from markdown.
As a library user I often use the documentation of this project and miss several features of a modern theme, for example:
- support for mobile devices
- support for dark and light styles
- automatic adaptation to the style of the operating system
- the presence of a general menu that is always visible
- the presence of a search
Regarding the accessibility of the current documentation, measured with PageSpeed, it is much lower (around 77)
compared to that measured with the "Material for MkDocs" documentation (around 89)
All these and other features are already in "Material for MkDocs" and this is why initially I only inserted a link to its website, because it seems to me much cheaper, in terms of commitment to the project, to adopt that theme instead than to modify the current one.
from markdown.
@pauloxnet thank you for listing some specific things that you would like to see supported/included in our documentation. I will note that I am very particular about some things and not-so-much about others. Even so, I am not a designer and that is why the current theme mostly borrows its CSS. With that in mind...
- support for mobile devices
A completely reasonable feature. Personally, I don't use mobile devices when referencing documentation, so I have no personal motivation to work on it. However, a solution which supports this would be given serious consideration.
- support for dark and light styles
I suppose. Personally I find dark themes to a usability/accessibility problem. When I am looking at my screen I look at the dark content, and ignore the light colored content (dark text on light background). So when a dark theme is used, I just see blank pages of darkness (because my eyes don't see the light colored text). Obviously, I am an outlier here due to the popularity of dark themes. However, I mention this because I cannot judge a dark theme. When I see one I just start blankly at the page for a couple minutes trying to understand what I'm supposed to even be looking at.
- automatic adaptation to the style of the operating system
If a dark theme is supported at all, absolutely. Then I will never be shown the dark theme. Presumably, some others would feel the same about the light theme??
- the presence of a general menu that is always visible
I'm indifferent to this. Actually, I find Material's global menu to be a usability problem. While working on our API docs I was using mkdocstrings documentation extensively and for the first time finally figured out how that menu works. But I still regularly get lost in the menu (why is the home page not at the outermost level? how do you navigate to an outer level from an inner one?). I like how our current theme works. From any page click on the index link and you get the sitemap which lists all pages. Or use next/previous to move through the documentation in a logical order. I realize that is not the only possible solution, but it is more usable that Material currently is.
- the presence of a search
As noted, this was inadvertently disabled in a recent update and a fix will be made with the next deployment of the docs.
Note that I have altered the title of this issue to better reflect the topic up for discussion.
So, while I am not included to try to develop my own design, I am also not inclined to use the Material theme. And when I look over other MkDocs theme, their templates rarely use best practices. In fact, when we were incorporating mkdocstrings into our documentation, we just used its Material theme because our templates were using best practices (mkdocstrings themes only provide templates, not CSS). The mkdocstrings devs where pleasantly surprised. Therefore, the best solution is likely to involve only minor adjustments to the templates and major changes to or replacement of the CSS. But we need a designer for that.
from markdown.
To be fair to the opening request, there are few, well maintained themes that offer great mobile interfaces. I think the reason why many gravitate towards material is that it is very well supported and does implement all of these things.
Personally, I am probably indifferent to the light/dark theme stuff, but the mobile interface is not great with the current theme.
from markdown.
Related Issues (20)
- Strange and inconsistent parsing of lists with headers and multiple lines HOT 6
- The title from `toc_tokens` ignores the `smarty` extension HOT 3
- BlockProcessor output wrapped in p tag HOT 9
- Trying to migrate from `markdown2`, lists without blank lines not working HOT 3
- "Unterminated character set" exception when using extra extension HOT 6
- <table> improperly wrapped by <p> when inside a list HOT 1
- Add Support for Tab Customization in Code Blocks HOT 3
- List not rendering correctly when preceded by word HOT 1
- add a buildin Mermaid extention HOT 1
- No table support? HOT 8
- GFM alerts HOT 2
- TOC extension: ignore headers above [TOC] marker HOT 2
- Fenced code blocks with newlines not parsed into html <code> blocks HOT 3
- convert \u2028 to <br>? HOT 2
- `abbr` extension breaks title attribute added using `attr_list` HOT 1
- Separate extensions from core
- no anchors are created HOT 8
- A line ending that is preceded by a backslash is not parsed as a hard line break HOT 3
- Abbreviation processing order alternative HOT 9
- 'markdown_extras' is not a registered tag library. Must be one of: HOT 7
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from markdown.