User guide

Installation

First, install the mkdocs-alabaster package from PyPI:

$ pip install mkdocs-alabaster

(If you used pipsi to install MkDocs, you should install the theme into that virtualenv as well:)

$ ~/.local/venvs/mkdocs/bin/pip install mkdocs-alabaster

Then enable the alabaster theme in your mkdocs.yml:

theme: alabaster

That's it! You now have the standard Alabaster theme set up. Read on for more configuration options/concerns.

Set markdown_extensions.toc.permalink to "¶" to add permalinks to the headers (visible on hover). “¶” is the default symbol used by Sphinx, you can use something else if you want.

Theme options

Relative path (from $PROJECT/docs/) to a logo image, which will appear in the upper left corner above the name of the project.

If logo is not set, your project name setting (from the MkDocs config) will be used in a text header instead. This preserves a link back to your homepage from inner doc pages.

extra.logo_name

Set to true to insert your site's project name under the logo image as text. Useful if your logo doesn't include the project name itself. Defaults to false.

extra.logo_title

Logo's title attribute. Default: your site_name.

extra.include_toc

Boolean, whether to include TOC in sidebar navigation or not. Default: false.

A dict of navigation links. Example:

extra:
  extra_nav_links:
    Fork me on GitHub: https://github.com/iamale/rock-cli

extra.show_powered_by

Show “Powered by” message, mentioning MkDocs and this theme. Default: true.

extra.sidebars

Specify sidebars shown in the left menu. By default, the following ones are shown, top to bottom:

  • about: logo and title (sidebars/about.html)
  • toc: current page table of contents (sidebars/toc.html)
  • related: links to the previous and next pages (sidebars/related.html)
  • search: quick search (sidebars/search.html)

To add your own sidebar, put its template in $THEME_DIR/sidebars and add its name to extra.sidebars:

extra:
  sidebars:
    - about
    - toc
    - my-awesome-sidebar # corresponds to `$THEME_DIR/sidebars/my-awesome-sidebar.html`
    - related
    - search

extra.homepage_nav

Show navigation tree on homepage. Default: true.

extra.homepage_sidebars

List of sidebar names shown in the left menu on the homepage only. By default, the following sidebars are shown, top to bottom:

  • about: logo and title (sidebars/about.html)
  • search: quick search (sidebars/search.html)

As you see, homepage is a little special as it doesn't have toc and related sidebars by default. The option extra.homepage_sidebars lets you easily override this behavior:

extra:
  homepage_sidebars:
    - about
    - toc
    - related
    - search

The table of contents sidebar includes only the current page's headings. If you want to have the global navigation in the menu, use an alternative sidebar called navigation:

extra:
  sidebars:
    - about
    - navigation
    - related
    - search

This is a port of the original Alabaster theme's sidebar of the same name.

Example

site_name: rock-cli
theme: alabaster
copyright: 2016 Alexander Pushkov

markdown_extensions:
  - toc:
      permalink: "¶"

extra:
  logo: logo.png
  logo_title: "Rocketbank logo"
  include_toc: yes
  extra_nav_links:
    Fork me on GitHub: https://github.com/iamale/rock-cli

自怼圈/年度番新

DU22.8
关于 ~ DebugUself with DAMA ;-)
点击注册~> 获得 100$ 体验券: DigitalOcean Referral Badge

订阅 substack 体验古早写作:

关注公众号, 持续获得相关各种嗯哼:
zoomquiet

蟒营®编程思维提高班Python版

**2021.01.11** 因大妈再次创业暂停定期开设, 转换为预约触发:
  • + 扫描预约入群, 学员每满 42 人即启动新一期训练营 ;-)
  • 101camp22.7
  • + 任何问题, 随时邮件提问可也: 
    askdama@googlegroups.com