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.ymlconfig file and set thethemeconfiguration option. You can write it with the theme name directly, astheme: readthedocs, and after you save the change the ReadTheDocs theme is applied. The longer form, with the name nested undertheme:, 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
themeoption as shown above
For small visual tweaks, you don't need a new theme. You can add CSS or JavaScript files through the
extra_cssandextra_javascriptoptions, provided the files are inside your documentation directory. For example, you can place astyle.cssfile next to your Markdown and list it underextra_cssinmkdocs.yml. For more complex changes, such as overriding templates, you need the themecustom_dirsetting 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 runmkdocs gh-deploy. MkDocs builds the docs and uses ghp-import to commit them to thegh-pagesbranch and push that branch to GitHub. Because the built site is pushed without a preview, verify changes first with thebuildorservecommands. 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
masterbranch 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 masterThe
--config-fileoption 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'smasterbranch instead.You can adjust the deploy with these
gh-deployoptions:-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 theremote_branchconfiguration setting can override it. Runmkdocs gh-deploy --helpfor 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
navsetting in yourmkdocs.ymlfile. For example, after creating a second page, you can add anavsetting with an entry for each page. Paths innavare relative to thedocs_diroption, which defaults todocs.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
navare 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 outnaventirely, 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
- Title: Put a title before the filename, such as
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