I like making websites. A lot.
Sometimes I make a new one every week.
Lately they have been around documentation for my GitHub projects - without writing a lot of code or boilerplate files. Or how turn an existing repo of over 100 markdown files at nested levels into a professional site.
I discuss some of experiences and challenges here, with links to my own projects. If you want to learn about MkDocs or Docsify, the links I provide include intro tutorials. And for Jekyll, the docs are great - jekyllrb.com.
Configured menus
For my projects, I like to have a top menu and/or sidebar and then populate this with hardcoded ordered values from a config. There are a few approaches to do this.
MkDocs
MkDocs is lighter on code I feel than Jekyll and provides much easier theming, sidebar and even search! Without knowing ins and of each theme. You can make it look like Read The Docs specifically. It supports sidebar nesting up to 2 levels only and set by config YAML
See my quickstart:
Docsify
Check out Docsify. It is built on VueJS but aside from the config options you don't have to write any VueJS or JavaScript code.
Theming is mostly about changing colors rather than layout. And out the box you get sidebar which handles nested pages setup in YAML (or it can infer from the current page).
You can also configure how many levels should be shown. Another nice thing is that the subitems in the sidebar get compressed when you're not on that section so it keeps it sanely readable.
Plus, you can have multiple menu config files to determine different sidebars. Then you use the header nav to get to sections of the site, where each section has a sidebar of relevant content. Which means less nesting in the sidebar but access to all the content.
Docsify has its limitations though. It is not SEO friendly (version 5 is supposed to have static site generation step, fingers crossed). And there are style issues like the menu button is hard to find on mobile - you can look into Docsify themeable as that solves some of the styling issues.
What about Jekyll?
I don't cover Jekyll here. Since unfortunately I haven't found any convenient low-code solutions for a sidebar in a Jekyll - solutions have to be engineered to one specifically with theme's page layout and CSS, compared with MkDocs and Docsify where it is easy to write once and repeat on other project. But maybe there's a Jekyll theme out that does what I need.
You can skip ahead to the Jekyll part in the next section though.
Dynamic menus
How to make menu change based on the current view.
Docsify again
Sometimes it is too tedious to build and maintain a menu by hand.
If you use Docsify with a single README.md file and multiple "pages" of content in one file, you can skip configuring a navbar and Docsify will build the menu for you. Users can use the sidebar or just scroll to navigate.
This is not practical when there is a lot content and having separate files is preferred.
Docsify had a simple appearance but can be complex to configure. It can be used in different ways well. So I have a tutorial site which is my currently most popular site which covers setting up Docsify and using in different ways like how the menu is generated.
Jekyll
Jekyll is a popular static site generator - I haven't used it much for docs sites as it can take a lot of boilerplate unless you find a food-related theme, but I like Jekyll for building sites in general.
Here is a demo site I made:
That uses the Minima theme - so you can focus on content using existing styling and navbar layout. If you just start creating pages, the navbar is smart enough to pick these up for you and put them in alphabetical order. Of course this doesn't work for many pages and it doesn't cater for nested pages but it's great for a start. It's also easy to add a value to the config to choose exactly which pages to show in the navbar and in what order.
Going back to the case I mentioned at the start of this post, here is my approach to organizing a repo of over 100 markdown files and about 4 levels of nesting so that a menu is populated at each level with only directly-related content. This keeps the menu minimal and also avoids having to update a config whenever you create, move or rename a page.
I made a Jekyll-based repo which let's me list content any number of levels down but only the current level's folders and pages are shown as a menu, so nesting doesn't get crazy. There's no sidebar though but maybe the dynamic menu that I've made can be turned into a sidebar that is also dynamic if that suits you.
My proof of concept repo before that:
That covers instructions on how to apply to your project, but the cheatsheets repo above has better styling and real content.
Maybe there's a way to do something similar in MkDocs as I did in Jekyll, but I don't know enough about MkDocs.
What about other tools?
I like learning knew tools, but I don't want to learn too many tools especially if they might have too much of learning curve for my low-code docs approach.
I've tried Hexo and Hugo but so far aren't convinced.
Conclusion
I have had a lot of menu and navigation thoughts that I wanted to get out. Did these help you? Do you have any approaches within these tools to recommend on sidebars, or dynamic menus for nested content?
Top comments (0)