Javascript has been updated to Bootstrap version 5.3.2 and CSS has been
updated to the the Bootswatch Cerulean theme version 5.3.2. Adding support
for a dark mode to the mkdocs theme is now possible.
All local colors (in base.css, extra.css, etc.) are now defined using
Bootstrap variables so that any future color modes (such as dark mode)
will be consistent.
Admonition styles have also been fully fleshed out with all colors being
Bootstrap colors (via variables) rather than our own custom colors.
Note that while Bootstrap version 5 dropped a dependency on jQuery, the
mkdocs theme is still making use of jQuery at this time. However, future
changes could remove the need for this dependency.
Co-authored-by: Oleh Prypin <oleh@pryp.in>
The homepage has been redesigned. The "Installation" and "Getting Started" sections were moved to their own respective pages. Then, the homepage was restyled so that the list of features appear as a grid of cards.
The developer specific pages were moved to a new section: `dev-guide`. Any old URLs redirect to the new ones.
We already link to the Deploying for Docs page which includes specific
instructions for various hosts. There is no need to also link to those
hosts in the Getting Started guide.
Closes#2210, closes#2104, closes#1890.
* Updated screenshots to reflect the actual pages in the tutorial (fixes#870).
* Added a few new screenshots to demonstrate more features (search).
* Replaced the `initial-config.png` screenshot with a code block.
* Corrected the inconsistant use of "you" and "we" throughout (use "you").
* Added links to various locations in the docs where appropriate.
* General cleanup, formatting, etc.
This change removes the dependency on mkdocs-bootstrap and mkdocs-bootswatch.
It also updates all references in the code. The only remaining connection is
when a user specifies one of these themes but they are not installed they get
slightly helpful error.
As of 40dc17e17e, any mention of the `--help` flag had been removed from
the documentation. A breif summary has been added here. However, the output
of `--help` has not been included as that can change in the future and
updating the docs every time a option is updated become unnesecarily
duplicative (as the command line is self-documenting). This fixes#767.
Also added README.md and CONTRIBUTING.md to the linter.
Note, that I am still getting one failer (in two locations). However
I consider that failer a bug in the linter and have reported it
upstream. We could disable that Rule (MD031), but as we are not
requiring the lint rules to pass presently, I just left it alone.
Also, while the code linter is set to allow lines 119 chars long,
I am using the Markdown linter's default of 80. Prose is easier to
read with shorter line lenghts, so I think it makes more sense to
use the default. Also, changing the default would have required
adding a config file. Adding a Ruby file for only one minor setting
seems silly, so I left it alone.
The current pages configuration looks like this:
pages:
- ['index.md', 'Home']
- ['writing-your-docs.md', 'User Guide', 'Writing your docs']
- ['styling-your-docs.md', 'User Guide', 'Styling your docs']
- ['configuration.md', 'User Guide', 'Configuration']
- ['about/license.md', 'About', 'License']
- ['about/release-notes.md', 'About', 'Release Notes']
- ['about/contributing.md', 'About', 'Contributing']
This has a number of flaws:
- It isn't clear how to add second levels of navigation for
newcomers. This is often queried and not easy to document.
- We are representing a tree structure as a set of flat items
that need to be merged. This creates some interesting edge
cases, for example:
- ['writing-your-docs.md', 'User Guide']
- ['styling-your-docs.md', 'User Guide', 'Styling your docs']
Is the first entry a page with the title User Guide? or a page
in the User Guide category with an automatic title.
- We are currently limited to two levels deep in the navigation.
Changing this with the current structure isn't trivial.
This change adds a new format which makes the above configuration
look like this:
pages:
- Home: index.md
- User Guide:
- user-guide/writing-your-docs.md
- user-guide/styling-your-docs.md
- user-guide/configuration.md
- About:
- License: about/license.md
- about/release-notes.md
- Contributing: about/contributing.md
With this structure, we can more easily see the documentation
tree and it is far more obvious what the navigation will look
like. It also removes the ambiguous edge cases and opens up the
possibility of adding further levels to the navigation more
easily.
This change restructures the pages configuration, but doesn't yet
allow users to add further levels in the navigation.
Fixes#6
