mkdocs-quickstart/search/search_index.json

{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"MkDocs Quickstart Started template for a MkDocs docs site on GH Pages - including CI Use the MkDocs ( make docs ) tool to create build a docs site around markdown docs. Follow the tutorial to add an existing project or create a project from scratch. The result will look like this project. Features How to use this project Follow the tutorial instructions Install and configure a new or existing project. Run it locally. Deploy it. Add a copy of this project to your repos View the live demo This site is hosted on GitHub Pages. See if you like it. Other themes are available - see the tutorial. The aim here is not be complete or explain all concepts. It is to provide a reference for common steps and choices needed when setting up a docs site, but still at a beginner-friendly level. This guide is based on the mkdocs.org tutorial.","title":"Home"},{"location":"#mkdocs-quickstart","text":"Started template for a MkDocs docs site on GH Pages - including CI Use the MkDocs ( make docs ) tool to create build a docs site around markdown docs. Follow the tutorial to add an existing project or create a project from scratch. The result will look like this project.","title":"MkDocs Quickstart"},{"location":"#features","text":"How to use this project Follow the tutorial instructions Install and configure a new or existing project. Run it locally. Deploy it. Add a copy of this project to your repos View the live demo This site is hosted on GitHub Pages. See if you like it. Other themes are available - see the tutorial. The aim here is not be complete or explain all concepts. It is to provide a reference for common steps and choices needed when setting up a docs site, but still at a beginner-friendly level. This guide is based on the mkdocs.org tutorial.","title":"Features"},{"location":"about-mkdocs/","text":"About MkDocs What is MkDocs? The description on the MkDocs site is: Project documentation with Markdown. MkDocs is a Python tool that generates a static site based on content written in Markdown. If you are new to markdown, see the Getting Started page on the Markdown Guide website. Resources mkdocs.org homepage mkdocs/mkdocs MkDocs Wiki - covering themes, plugins, recipes and more. Release notes for MkDocs. Reasons to use MkDocs Create an elegant, modern docs site for your project. Create a static site and serve from GitHub Pages easily. Low-code solution No need to write HTML or learn templating syntax needed Use your existing markdown files as content. Configure with a simple YAML file. Customizable. Add custom HTML if you want. Plugins available. Flexible theme choices. Includes search by default. Broken links to files (including from your navbar) will be detected at build time and shown as warnings. Do I need to know Python? MkDocs is built in Python (like Sphinx), but you don't have to write Python code. If you set up a Deploy flow right, you don't even have to set it up locally, though then you can't preview.","title":"About MkDocs"},{"location":"about-mkdocs/#about-mkdocs","text":"","title":"About MkDocs"},{"location":"about-mkdocs/#what-is-mkdocs","text":"The description on the MkDocs site is: Project documentation with Markdown. MkDocs is a Python tool that generates a static site based on content written in Markdown. If you are new to markdown, see the Getting Started page on the Markdown Guide website.","title":"What is MkDocs?"},{"location":"about-mkdocs/#resources","text":"mkdocs.org homepage mkdocs/mkdocs MkDocs Wiki - covering themes, plugins, recipes and more. Release notes for MkDocs.","title":"Resources"},{"location":"about-mkdocs/#reasons-to-use-mkdocs","text":"Create an elegant, modern docs site for your project. Create a static site and serve from GitHub Pages easily. Low-code solution No need to write HTML or learn templating syntax needed Use your existing markdown files as content. Configure with a simple YAML file. Customizable. Add custom HTML if you want. Plugins available. Flexible theme choices. Includes search by default. Broken links to files (including from your navbar) will be detected at build time and shown as warnings.","title":"Reasons to use MkDocs"},{"location":"about-mkdocs/#do-i-need-to-know-python","text":"MkDocs is built in Python (like Sphinx), but you don't have to write Python code. If you set up a Deploy flow right, you don't even have to set it up locally, though then you can't preview.","title":"Do I need to know Python?"},{"location":"tutorial/advanced/","text":"Advanced Beyond the basic configuration and content Once you've got the Set up Project section, you can customize further using this guide. Or skip this and go to Usage . Navbar nesting You can add an additional level to your navbar like this: nav: - Home: index.md - About: about.md - Foo: - Overview: foo/index.md - Bar: foo/bar.md The value can either be a string (as in the first case) or a map (as in the last case). This seems to be a YAML limitation but see also issue #1139 . Add config options See Configuration page on MkDocs site for options. Separate docs directory approach You can also structure your project to have the set up above nested inside a docs directory. This is useful you have a few other directories and you want to keep the project root clean. docs/ docs/ index.md theme/ main.html nav.html toc.html mkdocs.yml An example of this is the Poetry repo. That project is also how I got into MkDocs in the first place. Embedding To embed a gist, just copy and paste the embed script URL which is provided on a gist. e.g. <script src=\"https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js\"></script>","title":"Advanced"},{"location":"tutorial/advanced/#advanced","text":"Beyond the basic configuration and content Once you've got the Set up Project section, you can customize further using this guide. Or skip this and go to Usage .","title":"Advanced"},{"location":"tutorial/advanced/#navbar-nesting","text":"You can add an additional level to your navbar like this: nav: - Home: index.md - About: about.md - Foo: - Overview: foo/index.md - Bar: foo/bar.md The value can either be a string (as in the first case) or a map (as in the last case). This seems to be a YAML limitation but see also issue #1139 .","title":"Navbar nesting"},{"location":"tutorial/advanced/#add-config-options","text":"See Configuration page on MkDocs site for options.","title":"Add config options"},{"location":"tutorial/advanced/#separate-docs-directory-approach","text":"You can also structure your project to have the set up above nested inside a docs directory. This is useful you have a few other directories and you want to keep the project root clean. docs/ docs/ index.md theme/ main.html nav.html toc.html mkdocs.yml An example of this is the Poetry repo. That project is also how I got into MkDocs in the first place.","title":"Separate docs directory approach"},{"location":"tutorial/advanced/#embedding","text":"To embed a gist, just copy and paste the embed script URL which is provided on a gist. e.g. <script src=\"https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js\"></script>","title":"Embedding"},{"location":"tutorial/deploy/","text":"Deploy Build and deploy to a remote public site See Deploying Your Docs on the Mkdocs site for more details. GitHub Pages How to deploy your docs site to GitHub Pages. Follow one of the approaches below: Run deploy command - Run a MkDocs CLI command locally to deploy. Deploy with GitHub Actions - Use the project's CI workflow in the cloud to build and deploy to GH Pages on commits pushed to master. Then go to your repo's Settings and Pages then enable GitHub Pages on the gh-pages branch's root. Note this is for a Project Page on a subpath, you will have to make adjustments to the command below if you want an Organization or User Page on the root path. Run deploy command Run a MkDocs CLI command locally to deploy MkDocs needs to know where to publish commits on GitHub - so make sure you are working with a repo that you cloned, or that you initialize the local repo and add a remote repo. Run this command locally: $ make d That will use Makefile to run the following: $ mkdocs gh-deploy --strict --force That will do the following: Clean and build to site directory. Force push to gh-pages branch, overwriting any changes which were pushed from another build. Then go to your repo on GitHub, look at the Environment tab. When it is done building, click View deployment to see your site. e.g. michaelcurrin.github.io/mkdocs-quickstart/ See deploy options in the help: $ mkdocs gh-deploy --help Deploy with GitHub Actions Set up continuous deployment config to enable deploys on a change to files on GitHub When you make changes to your docs config or the docs directory, especially editing on GitHub directly, it's often useful to have the docs site build and deploy automatically in a remote environment. This is provided for free by GitHub. See the docs.yml workflow provided with this project. You don't have to change anything there. The token will be generated for you by GitHub Actions.","title":"Deploy"},{"location":"tutorial/deploy/#deploy","text":"Build and deploy to a remote public site See Deploying Your Docs on the Mkdocs site for more details.","title":"Deploy"},{"location":"tutorial/deploy/#github-pages","text":"How to deploy your docs site to GitHub Pages. Follow one of the approaches below: Run deploy command - Run a MkDocs CLI command locally to deploy. Deploy with GitHub Actions - Use the project's CI workflow in the cloud to build and deploy to GH Pages on commits pushed to master. Then go to your repo's Settings and Pages then enable GitHub Pages on the gh-pages branch's root. Note this is for a Project Page on a subpath, you will have to make adjustments to the command below if you want an Organization or User Page on the root path.","title":"GitHub Pages"},{"location":"tutorial/deploy/#run-deploy-command","text":"Run a MkDocs CLI command locally to deploy MkDocs needs to know where to publish commits on GitHub - so make sure you are working with a repo that you cloned, or that you initialize the local repo and add a remote repo. Run this command locally: $ make d That will use Makefile to run the following: $ mkdocs gh-deploy --strict --force That will do the following: Clean and build to site directory. Force push to gh-pages branch, overwriting any changes which were pushed from another build. Then go to your repo on GitHub, look at the Environment tab. When it is done building, click View deployment to see your site. e.g. michaelcurrin.github.io/mkdocs-quickstart/ See deploy options in the help: $ mkdocs gh-deploy --help","title":"Run deploy command"},{"location":"tutorial/deploy/#deploy-with-github-actions","text":"Set up continuous deployment config to enable deploys on a change to files on GitHub When you make changes to your docs config or the docs directory, especially editing on GitHub directly, it's often useful to have the docs site build and deploy automatically in a remote environment. This is provided for free by GitHub. See the docs.yml workflow provided with this project. You don't have to change anything there. The token will be generated for you by GitHub Actions.","title":"Deploy with GitHub Actions"},{"location":"tutorial/installation/","text":"Installation How to install MkDocs locally. Requirements Python 3 Make - standard on macOS and Linux but can be installed on Windows too. Install system dependencies Set up a new repo Follow the Tutorial page to set up a project from scratch. Or click this create your own copy of the repo. Then clone your repo. e.g. $ git clone git@github.com:MichaelCurrin/mkdocs-quickstart.git $ cd mkdocs-quickstart Install project dependencies Install MkDocs locally For more info, see the Installation page on the MkDocs site. Install in a virtual environment Create a virtual environment at the project root - this is used to isolate project packages from the global packages. $ python3 -m venv venv Activate the environment. $ source venv/bin/activate Install mkdocs - this is covered in the project requirements file. $ cd docs $ make install Note - mkdocs 1.2 causes a break on force pushes, so this is excluded in the requirements. See issue #2447 . Install globally If you prefer to install MkDocs once and reuse it across projects, then you can install it globally instead. MkDocs is available using package managers like apt-get , homebrew and yum . Or you can install like this: $ python3 -m pip install mkdocs If you get prompted for sudo use, then cancel and run again with -U flag for user-level install.","title":"Installation"},{"location":"tutorial/installation/#installation","text":"How to install MkDocs locally.","title":"Installation"},{"location":"tutorial/installation/#requirements","text":"Python 3 Make - standard on macOS and Linux but can be installed on Windows too.","title":"Requirements"},{"location":"tutorial/installation/#install-system-dependencies","text":"","title":"Install system dependencies"},{"location":"tutorial/installation/#set-up-a-new-repo","text":"Follow the Tutorial page to set up a project from scratch. Or click this create your own copy of the repo. Then clone your repo. e.g. $ git clone git@github.com:MichaelCurrin/mkdocs-quickstart.git $ cd mkdocs-quickstart","title":"Set up a new repo"},{"location":"tutorial/installation/#install-project-dependencies","text":"Install MkDocs locally For more info, see the Installation page on the MkDocs site.","title":"Install project dependencies"},{"location":"tutorial/installation/#install-in-a-virtual-environment","text":"Create a virtual environment at the project root - this is used to isolate project packages from the global packages. $ python3 -m venv venv Activate the environment. $ source venv/bin/activate Install mkdocs - this is covered in the project requirements file. $ cd docs $ make install Note - mkdocs 1.2 causes a break on force pushes, so this is excluded in the requirements. See issue #2447 .","title":"Install in a virtual environment"},{"location":"tutorial/installation/#install-globally","text":"If you prefer to install MkDocs once and reuse it across projects, then you can install it globally instead. MkDocs is available using package managers like apt-get , homebrew and yum . Or you can install like this: $ python3 -m pip install mkdocs If you get prompted for sudo use, then cancel and run again with -U flag for user-level install.","title":"Install globally"},{"location":"tutorial/setup-project/","text":"Set up project How to create a MkDocs site from scratch This is a summary of the tutorial on mkdocs.org . How to use this guide Use one of the approaches below: Create a quickstart project with the new command covered in Create a starter site . Follow the extended guide to create a Set up up docs site by hand. Basic structure This is the simplest MkDocs site you can make: docs/ index.md - Homepage in the docs directory (by default). mkdocs.yml Config at the root - control appearance and navigation of your site. See this project's docs/mkdocs.yml file on GitHub. Notes on fields for the config: site_name - title of your site. site_description - used as a description for SEO and you could use it somewhere in your template. site_url - now a required field when running a deploy. Include the subpath on the domain. If your site is not ready to be hosted, set this field to an empty string. repo_url - for Edit on GitHub button. See docs . edit_uri - defaults to edit/master/docs/ , which includes docs directory of markdown files inside your repo root. But, if the site's root is in an outer docs directory, then you need to also add that, so paths do not break. e.g. edit/master/docs/docs . See docs Requirements file A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure pip install mkdocs and pip install THEME lines are your instructions. If you want to add, then include requirements.txt at the root. If your project is already a Python project, you might prefer to add mkdocs in requirements-dev.txt or at docs/requirements.txt to keep it isolated.This file should have mkdocs in it and also any themes if needed. Create a starter site Run this command to create a starter site. This make the steps below go quicker. cd my-project mkdocs new PATH The result will be same as the Basic structure defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's new.py module. Set up a docs site Tip: Optionally use the new command covered above to set up the config and index page first and then continue . Create doc pages. Create a docs directory. Create index.md as your homepage. Create other markdown pages (optional). Use placeholder content if you want to move on and then come back to expand them. If you have any existing markdown docs, these will work too. Set up config. Create mkdocs.yml at the project root. Set up a navbar there. Choose a theme. Create a favicon (optional). It will be picked up at this path: docs/img/favicon.ico . Add to your .gitignore . Add build directory. This will prevent it from being versioned on master branch. Add virtual environment, if using one. You project should now look this this: docs/ index.md More pages... mkdocs.yml .gitignore venv requirements.txt - optional Sample content Ignore file .gitignore site/ venv Navbar mkdocs.yml nav: - Home: index.md - About: about.md Themes Builtin Use a builtin theme that comes with MkDocs. The default. theme: mkdocs Using ReadTheDocs theme and alternative config syntax. theme: name: readthedocs Find more supported themes . If it doesn't immediately, you'll have to use pip to install it and add to a requirements.txt file. ReadTheDocs Dropdown theme See below using mkdocs-rtd-dropdown . requirements.txt : mkdocs-rtd-dropdown mkdocs.yml : theme: name: 'rtd-dropdown' Material for MkdDocs theme See the MkDocs for Material homepage. See the Set up page for config options. requirements.txt : mkdocs-material-extensions>=1.0 mkdocs.yml : theme: name: 'material'","title":"Set up project"},{"location":"tutorial/setup-project/#set-up-project","text":"How to create a MkDocs site from scratch This is a summary of the tutorial on mkdocs.org .","title":"Set up project"},{"location":"tutorial/setup-project/#how-to-use-this-guide","text":"Use one of the approaches below: Create a quickstart project with the new command covered in Create a starter site . Follow the extended guide to create a Set up up docs site by hand.","title":"How to use this guide"},{"location":"tutorial/setup-project/#basic-structure","text":"This is the simplest MkDocs site you can make: docs/ index.md - Homepage in the docs directory (by default). mkdocs.yml Config at the root - control appearance and navigation of your site. See this project's docs/mkdocs.yml file on GitHub. Notes on fields for the config: site_name - title of your site. site_description - used as a description for SEO and you could use it somewhere in your template. site_url - now a required field when running a deploy. Include the subpath on the domain. If your site is not ready to be hosted, set this field to an empty string. repo_url - for Edit on GitHub button. See docs . edit_uri - defaults to edit/master/docs/ , which includes docs directory of markdown files inside your repo root. But, if the site's root is in an outer docs directory, then you need to also add that, so paths do not break. e.g. edit/master/docs/docs . See docs","title":"Basic structure"},{"location":"tutorial/setup-project/#requirements-file","text":"A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure pip install mkdocs and pip install THEME lines are your instructions. If you want to add, then include requirements.txt at the root. If your project is already a Python project, you might prefer to add mkdocs in requirements-dev.txt or at docs/requirements.txt to keep it isolated.This file should have mkdocs in it and also any themes if needed.","title":"Requirements file"},{"location":"tutorial/setup-project/#create-a-starter-site","text":"Run this command to create a starter site. This make the steps below go quicker. cd my-project mkdocs new PATH The result will be same as the Basic structure defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's new.py module.","title":"Create a starter site"},{"location":"tutorial/setup-project/#set-up-a-docs-site","text":"Tip: Optionally use the new command covered above to set up the config and index page first and then continue . Create doc pages. Create a docs directory. Create index.md as your homepage. Create other markdown pages (optional). Use placeholder content if you want to move on and then come back to expand them. If you have any existing markdown docs, these will work too. Set up config. Create mkdocs.yml at the project root. Set up a navbar there. Choose a theme. Create a favicon (optional). It will be picked up at this path: docs/img/favicon.ico . Add to your .gitignore . Add build directory. This will prevent it from being versioned on master branch. Add virtual environment, if using one. You project should now look this this: docs/ index.md More pages... mkdocs.yml .gitignore venv requirements.txt - optional","title":"Set up a docs site"},{"location":"tutorial/setup-project/#sample-content","text":"","title":"Sample content"},{"location":"tutorial/setup-project/#ignore-file","text":".gitignore site/ venv","title":"Ignore file"},{"location":"tutorial/setup-project/#navbar","text":"mkdocs.yml nav: - Home: index.md - About: about.md","title":"Navbar"},{"location":"tutorial/setup-project/#themes","text":"","title":"Themes"},{"location":"tutorial/setup-project/#builtin","text":"Use a builtin theme that comes with MkDocs. The default. theme: mkdocs Using ReadTheDocs theme and alternative config syntax. theme: name: readthedocs Find more supported themes . If it doesn't immediately, you'll have to use pip to install it and add to a requirements.txt file.","title":"Builtin"},{"location":"tutorial/setup-project/#readthedocs-dropdown-theme","text":"See below using mkdocs-rtd-dropdown . requirements.txt : mkdocs-rtd-dropdown mkdocs.yml : theme: name: 'rtd-dropdown'","title":"ReadTheDocs Dropdown theme"},{"location":"tutorial/setup-project/#material-for-mkddocs-theme","text":"See the MkDocs for Material homepage. See the Set up page for config options. requirements.txt : mkdocs-material-extensions>=1.0 mkdocs.yml : theme: name: 'material'","title":"Material for MkdDocs theme"},{"location":"tutorial/tldr/","text":"TL;DR A simplified version of the tutorial. Local setup Install pip install mkdocs Set up project mkdocs new . or Run mkdocs serve View on localhost:8000 Deploy to remote site Run deploy command locally Deploy to GitHub Pages mkdocs gh-deploy View published site on GitHub Pages at https://USERNAME.github.io/REPO-NAME/ Run continuous integration For CI/CD deploy, use GitHub Actions with an action such as Deploy MkDocs . Or use Netlify. This is not covered in this tutorial.","title":"TL;DR"},{"location":"tutorial/tldr/#tldr","text":"A simplified version of the tutorial.","title":"TL;DR"},{"location":"tutorial/tldr/#local-setup","text":"Install pip install mkdocs Set up project mkdocs new . or Run mkdocs serve View on localhost:8000","title":"Local setup"},{"location":"tutorial/tldr/#deploy-to-remote-site","text":"","title":"Deploy to remote site"},{"location":"tutorial/tldr/#run-deploy-command-locally","text":"Deploy to GitHub Pages mkdocs gh-deploy View published site on GitHub Pages at https://USERNAME.github.io/REPO-NAME/","title":"Run deploy command locally"},{"location":"tutorial/tldr/#run-continuous-integration","text":"For CI/CD deploy, use GitHub Actions with an action such as Deploy MkDocs . Or use Netlify. This is not covered in this tutorial.","title":"Run continuous integration"},{"location":"tutorial/usage/","text":"Usage Build and preview a site locally Make sure to run all commands from the docs directory, as that is where Makefile is. $ cd docs CLI help $ make help default: install all: install build h help: install: upgrade: s serve: b build: d deploy: Serve docs This will build the docs in memory (not to disk) and serve an auto-reloading server. $ make serve Then open in your browser: localhost:8000 Build docs Build docs site to site directory. This is useful for a CI flow. $ make build","title":"Usage"},{"location":"tutorial/usage/#usage","text":"Build and preview a site locally Make sure to run all commands from the docs directory, as that is where Makefile is. $ cd docs","title":"Usage"},{"location":"tutorial/usage/#cli-help","text":"$ make help default: install all: install build h help: install: upgrade: s serve: b build: d deploy:","title":"CLI help"},{"location":"tutorial/usage/#serve-docs","text":"This will build the docs in memory (not to disk) and serve an auto-reloading server. $ make serve Then open in your browser: localhost:8000","title":"Serve docs"},{"location":"tutorial/usage/#build-docs","text":"Build docs site to site directory. This is useful for a CI flow. $ make build","title":"Build docs"}]}