EveryPage

Unofficial example

Ask the MkDocs docs

The Ask this site box, reading www.mkdocs.org. Type a question and it answers from those pages, with links.

Loading the box…

An unofficial example. Ask this site is not affiliated with or endorsed by the MkDocs project. The MkDocs docs belong to their authors and are read here under their BSD-2-Clause licence.

Questions it answered

Real answers from this box.

  • How do I change the theme?

    To change the theme, edit the mkdocs.yml config file and set the theme configuration option. You can write it with the theme name directly, as theme: readthedocs, and after you save the change the ReadTheDocs theme is applied. The longer form, with the name nested under theme:, also works.

    MkDocs includes two built-in themes, and many third-party themes are also available. The built-in ones are:

    • mkdocs: the default MkDocs theme, one of the two built-in options
    • readthedocs: the ReadTheDocs theme, set with the theme option as shown above

    For small visual tweaks, you don't need a new theme. You can add CSS or JavaScript files through the extra_css and extra_javascript options, provided the files are inside your documentation directory. For example, you can place a style.css file next to your Markdown and list it under extra_css in mkdocs.yml. For more complex changes, such as overriding templates, you need the theme custom_dir setting instead.

    Answered from Choosing your Theme, Getting Started with MkDocs — Theming our documentation, Customizing Your Theme, customizing-your-theme.md (cont. 16)

  • How do I deploy to GitHub Pages?

    GitHub Pages has two site types, Project Pages and User and Organization Pages, which deploy differently.

    For a Project Pages site, checkout the primary working branch (usually master) of your documentation repository and run mkdocs gh-deploy. MkDocs builds the docs and uses ghp-import to commit them to the gh-pages branch and push that branch to GitHub. Because the built site is pushed without a preview, verify changes first with the build or serve commands. Do not hand-edit files in the pages repository, since the next deploy overwrites them, and untracked or uncommitted files in the local repository are included in the deployed pages.

    For a User or Organization Pages site, the files go to the master branch of a dedicated repository named after your GitHub account, so you need working copies of both repositories. After verifying your project, change into the account repository and run:

    mkdocs gh-deploy --config-file../my-project/mkdocs.yml --remote-branch master

    The --config-file option is required because the configuration file is no longer in the current directory. If you forget to change directories, the command commits to your project's master branch instead.

    You can adjust the deploy with these gh-deploy options:

    • -b, --remote-branch: sets the branch to commit to, overriding the config value.
    • -f, --config-file: provides a specific MkDocs config file.
    • -m, --message: sets the commit message, with Commit {sha} and MkDocs {version} available as expansions.
    • -r, --remote-name: sets the remote name to commit to.
    • --force: forces the push to the repository.
    • --no-history: replaces the whole Git history with one new commit.

    The default remote branch is gh-pages, and the remote_branch configuration setting can override it. Run mkdocs gh-deploy --help for the full list of options.

    Answered from Deploying your docs — GitHub Pages, Deploying your docs — Project Pages, Deploying your docs — Organization and User Pages, Command Line Interface — mkdocs gh-deploy, Configuration — remote_branch

  • How do I add a page to the navigation?

    To add a page to the navigation, list it under the nav setting in your mkdocs.yml file. For example, after creating a second page, you can add a nav setting with an entry for each page. Paths in nav are relative to the docs_dir option, which defaults to docs.

    You can also control how the page appears in the menu:

    • Title: Put a title before the filename, such as About: about.md, to override the page's inferred title.
    • Sections: Group related pages under a section title by nesting them beneath it. Sections are containers only and cannot have a page assigned to them.

    Pages that are not listed in nav are still built into the site, but they are not linked from the global navigation and are not included in the previous and next links. If you leave out nav entirely, MkDocs creates the navigation automatically from all Markdown files in the documentation directory, sorted alphabetically by filename.

    Answered from Getting Started with MkDocs — Adding pages, Writing your docs — Configure Pages and Navigation

Add this to your own docs

Paste your docs address to try it, free and without signing up. Then it is one line of code.

DocusaurusGitBookMintlifyWordPressReadMeMkDocsVitePressStarlightSphinxHugoJekyllNext.jsGhostWebflow