search

MarkBind / markbind

MarkBind is a tool for generating content-heavy websites from source files in Markdown format
https://markbind.org/
MIT License
135 stars 124 forks source link

Improve documentation of navigation bars and header.md files #1869

Open kaixin-hc opened 2 years ago

kaixin-hc commented 2 years ago

Is there an existing issue for this?

Any related issues?

1791, which deals with documentation improvements on similar pages

Tell us about your environment

MacOS Monterey

MarkBind version

3.1.1

What did you do? Describe the bug

The idea of a header.md file in {your-site}/_markbind/headers/header.md is alluded to, but the reasoning and set up of this file is not described clearly anywhere. Overall, the documentation of the navbar and site navigation can be improved.

There are some references and broken links relating to it in the documentation; specifically in https://markbind.org/userGuide/components/navigation.html#navbars .

Note: Navbars should be placed within a header file to ensure that they are correctly positioned at the top of the page, above the site navigation and page navigation menus.

which is a broken link to https://markbind.org/userGuide/tweakingThePageStructure.html#headers, a section which does not exist. The other two sections referenced do not hold additional relevant information.

The following quote isn't live but is part of the latest master:

"In {your-site}/_markbind/headers/header.md, you can change <navbar type="dark/primary/light"> to <navbar type="none" add-class="bg-warning/danger/info/primary/success"> to apply Bootstrap background styles."

Steps to reproduce

No response

Expected behavior

A clear understanding of if a header.md file is necessary, and what functionality using such a file offers. I think it's worthwhile to think about how to restructure and improve these two pages. For example, the section on navbar link highlighting does not describe the functionality, just shows a large code example and then a table of options

Actual behavior

I suspect the sections referenced were a previous implementation of header content that has since been made obsolete...? Though a cursory search of the last gitblame makes it seem that the reference to header.md file was incidental in trying to demonstrate themes.

Anything else?

No response

ang-zeyu commented 2 years ago

Thanks for the catch. This a really old remnant from 2~3 years back when we had a more rigid (header.md / navbar.md / sitenav.md) sort of layout system I missed out.

Let's update the documentation to reflect the relevant concerns within an expressive layout system for the cases of: