mirror of
https://github.com/MichaelCurrin/mkdocs-quickstart.git
synced 2026-06-17 08:35:40 +02:00
Compare commits
157 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Michael Currin
|
e568b53c0b | ||
|
Michael Currin
|
5dd48b2724 | ||
|
Michael Currin
|
7b27555c9c | ||
|
Michael Currin
|
f124cfed0c | ||
|
Michael Currin
|
ad7a922caf | ||
|
Michael Currin
|
3b42b265ed | ||
|
Michael Currin
|
dae5dbde87 | ||
|
Michael Currin
|
2018fa399b | ||
|
Michael Currin
|
0484dbbb36 | ||
|
Michael Currin
|
898c72051c | ||
|
Michael Currin
|
e5bcc9ac5f | ||
|
Michael Currin
|
158e6dc938 | ||
|
Michael Currin
|
828bf66208 | ||
|
Michael Currin
|
16e004a200 | ||
|
Michael Currin
|
acd0ac400d | ||
|
Michael Currin
|
1bcc5ce191 | ||
|
Michael Currin
|
4fb05cb607 | ||
|
Michael Currin
|
a0e179cf37 | ||
|
Michael Currin
|
aef52ecef8 | ||
|
Michael Currin
|
c847fcad63 | ||
|
Michael Currin
|
12e2d22aeb | ||
|
Michael Currin
|
8781bdacc6 | ||
|
Michael Currin
|
1a7fb2188e | ||
|
Michael Currin
|
bab097381d | ||
|
Michael Currin
|
a29dcb851f | ||
|
Michael Currin
|
f78e2a23b9 | ||
|
Michael Currin
|
a90d16525f | ||
|
Michael Currin
|
4cb7066ac6 | ||
|
Michael Currin
|
b0ce48a07c | ||
|
Michael Currin
|
e7f49d04b7 | ||
|
Michael Currin
|
2c0468d4bc | ||
|
Michael Currin
|
3de9789c2a | ||
|
Michael Currin
|
17919978b1 | ||
|
Michael Currin
|
8a1ad62921 | ||
|
Michael Currin
|
48218d64da | ||
|
Michael Currin
|
6f2b3c818e | ||
|
Michael Currin
|
e49c7ae2b3 | ||
|
Michael Currin
|
619a224358 | ||
|
Michael Currin
|
adf4d392f8 | ||
|
Michael Currin
|
dacf3464e2 | ||
|
Michael Currin
|
566de0e514 | ||
|
Michael Currin
|
8bd56b6906 | ||
|
Michael Currin
|
2b289a59b0 | ||
|
Michael Currin
|
3f0006ac82 | ||
|
Michael Currin
|
76e04dde8e | ||
|
Michael Currin
|
8601582a74 | ||
|
Michael Currin
|
f22c1fe04d | ||
|
Michael Currin
|
e577bb912b | ||
|
Michael Currin
|
887d08bc3c | ||
|
Michael Currin
|
473580b7d6 | ||
|
Michael Currin
|
99fb0757c7 | ||
|
Michael Currin
|
a028e5c228 | ||
|
Michael Currin
|
49d6ee84a7 | ||
|
Michael Currin
|
f21ac0fe3c | ||
|
Michael Currin
|
3b5f31d73d | ||
|
Michael Currin
|
3a743ae48f | ||
|
Michael Currin
|
fdbbb73cd6 | ||
|
Michael Currin
|
953967dda8 | ||
|
Michael Currin
|
35ce122bd8 | ||
|
Michael Currin
|
89fbc16c26 | ||
|
Michael Currin
|
e7800bc936 | ||
|
Michael Currin
|
54be3ff415 | ||
|
Michael Currin
|
b48560c99d | ||
|
Michael Currin
|
d14aca853a | ||
|
Michael Currin
|
11c1377a9f | ||
|
Michael Currin
|
5e8b217c8d | ||
|
Michael Currin
|
b842ce958e | ||
|
Michael Currin
|
787dc334a1 | ||
|
Michael Currin
|
286e8c6f0d | ||
|
Michael Currin
|
1decccd809 | ||
|
Michael Currin
|
6bef7960f0 | ||
|
Michael Currin
|
645a052e22 | ||
|
Michael Currin
|
da67a34443 | ||
|
Michael Currin
|
4a9f27222a | ||
|
Michael Currin
|
8feabd1a43 | ||
|
Michael Currin
|
ae37b3874d | ||
|
Michael Currin
|
3630bab42c | ||
|
Michael Currin
|
4726a67ef3 | ||
|
Michael Currin
|
c25398473f | ||
|
Michael Currin
|
b27fe05ebe | ||
|
Michael Currin
|
01e7c407b0 | ||
|
Michael Currin
|
8434d546bb | ||
|
Michael Currin
|
4753edcbe9 | ||
|
Michael Currin
|
7e69b48377 | ||
|
Michael Currin
|
6a5cfe2377 | ||
|
Michael Currin
|
7177e48983 | ||
|
Michael Currin
|
989e13de5e | ||
|
Michael Currin
|
4c169b9981 | ||
|
Michael Currin
|
81e9147b2b | ||
|
Michael Currin
|
6f7122d7cd | ||
|
Michael Currin
|
f537e68f5f | ||
|
michaelcurrin
|
49b3a80578 | ||
|
michaelcurrin
|
dbc5a5a15e | ||
|
michaelcurrin
|
bcd5d97980 | ||
|
michaelcurrin
|
bf0b822e71 | ||
|
michaelcurrin
|
1743e1c99f | ||
|
michaelcurrin
|
a4858ef9ef | ||
|
michaelcurrin
|
24fcac8f5b | ||
|
michaelcurrin
|
aa732678ba | ||
|
michaelcurrin
|
66f0fa8cd7 | ||
|
michaelcurrin
|
eebbe99358 | ||
|
michaelcurrin
|
0f4f91bbc8 | ||
|
michaelcurrin
|
bbdbd30f69 | ||
|
michaelcurrin
|
09f8bc898f | ||
|
michaelcurrin
|
8aa74eb6b0 | ||
|
michaelcurrin
|
9571f1ad46 | ||
|
michaelcurrin
|
91582e3392 | ||
|
michaelcurrin
|
b4f9479472 | ||
|
michaelcurrin
|
7b0ffe8c9d | ||
|
michaelcurrin
|
a8d346de5d | ||
|
michaelcurrin
|
aa4bf1088c | ||
|
michaelcurrin
|
84b65458a2 | ||
|
michaelcurrin
|
f4f6a6861d | ||
|
michaelcurrin
|
735ab35a26 | ||
|
michaelcurrin
|
65d7c7343b | ||
|
Michael Currin
|
0ae70d2fcd | ||
|
Michael Currin
|
7b729ba759 | ||
|
Michael Currin
|
e0d9117274 | ||
|
Michael Currin
|
928f697e0c | ||
|
Michael Currin
|
f45d546ccf | ||
|
michaelcurrin
|
3400d5c4bb | ||
|
michaelcurrin
|
95f5e64589 | ||
|
michaelcurrin
|
1b92ee3dde | ||
|
michaelcurrin
|
d2521f69a4 | ||
|
michaelcurrin
|
e14b88702e | ||
|
michaelcurrin
|
10bb3fabcc | ||
|
michaelcurrin
|
ddb2e02ac0 | ||
|
michaelcurrin
|
9a4668db47 | ||
|
michaelcurrin
|
375db30200 | ||
|
Michael Currin
|
15e528c07f | ||
|
Michael Currin
|
b61b9d1a70 | ||
|
Michael Currin
|
2d5113a961 | ||
|
Michael Currin
|
2b4544320b | ||
|
Michael Currin
|
52a8f7862a | ||
|
Michael Currin
|
bdcd8f367c | ||
|
michaelcurrin
|
cfb5853123 | ||
|
michaelcurrin
|
d59ed88866 | ||
|
michaelcurrin
|
7e5650e241 | ||
|
michaelcurrin
|
dc05d52b62 | ||
|
Michael Currin
|
3e735f3893 | ||
|
michaelcurrin
|
7a07748602 | ||
|
Michael Currin
|
06171073a3 | ||
|
Michael Currin
|
0b9cc10056 | ||
|
Michael Currin
|
29f21df22c | ||
|
Michael Currin
|
4f2c416522 | ||
|
Michael Currin
|
a1396d49f2 | ||
|
Michael Currin
|
aa7a424e6e | ||
|
Michael Currin
|
0fc7cffc9d | ||
|
Michael Currin
|
21c5bc617d | ||
|
Michael Currin
|
a8aa77ef92 | ||
|
Michael Currin
|
a1eb0384a2 | ||
|
Michael Currin
|
5b6b7f5842 | ||
|
Michael Currin
|
fa02026620 | ||
|
Michael Currin
|
bac151be2d | ||
|
Michael Currin
|
896b42e139 | ||
|
Michael Currin
|
f43d157d4b | ||
|
michaelcurrin
|
d845906d2c |
@@ -0,0 +1,36 @@
|
||||
name: Deploy Docs
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
build-deploy:
|
||||
name: Build and deploy docs
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout 🛎️
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Set up Python 3 ⚙️ 🐍
|
||||
uses: actions/setup-python@v2
|
||||
|
||||
- name: Cache dependencies 💾
|
||||
uses: actions/cache@v2
|
||||
with:
|
||||
path: ~/.cache/pip
|
||||
key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-pip-
|
||||
${{ runner.os }}-
|
||||
|
||||
- name: Install dependencies 🔧
|
||||
working-directory: docs
|
||||
run: make install
|
||||
|
||||
- name: Build and deploy to GitHub Pages 🏗️ 🚀
|
||||
working-directory: docs
|
||||
run: make deploy
|
||||
@@ -0,0 +1,3 @@
|
||||
venv
|
||||
|
||||
site/
|
||||
Vendored
+3
@@ -0,0 +1,3 @@
|
||||
{
|
||||
"python.pythonPath": "venv/bin/python"
|
||||
}
|
||||
@@ -1,146 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
|
||||
<link rel="shortcut icon" href="/mkdocs-quickstart/img/favicon.ico">
|
||||
<title>MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="/mkdocs-quickstart/css/theme.css" />
|
||||
<link rel="stylesheet" href="/mkdocs-quickstart/css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script src="/mkdocs-quickstart/js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="/mkdocs-quickstart/js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="/mkdocs-quickstart/." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="/mkdocs-quickstart//search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/.">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/tutorial/tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/tutorial/installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/tutorial/setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/tutorial/advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/tutorial/usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="/mkdocs-quickstart/tutorial/deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="/mkdocs-quickstart/.">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="/mkdocs-quickstart/.">Docs</a> »</li>
|
||||
|
||||
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
|
||||
<h1 id="404-page-not-found">404</h1>
|
||||
|
||||
<p><strong>Page not found</strong></p>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '/mkdocs-quickstart/';</script>
|
||||
<script src="/mkdocs-quickstart/js/theme_extra.js" defer></script>
|
||||
<script src="/mkdocs-quickstart/js/theme.js" defer></script>
|
||||
<script src="/mkdocs-quickstart/search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2020 - 2021 MichaelCurrin
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,116 @@
|
||||
# MkDocs Quickstart
|
||||
> Starter template for a MkDocs docs site on GH Pages - including CI
|
||||
|
||||
[](https://github.com/MichaelCurrin/mkdocs-quickstart/actions)
|
||||
[](https://github.com/MichaelCurrin/mkdocs-quickstart/releases/)
|
||||
[](#license)
|
||||
|
||||
[](https://python.org)
|
||||
[](https://www.mkdocs.org/)
|
||||
[](https://github.com/features/actions)
|
||||
|
||||
A template, live demo and tutorial for how to set up a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.
|
||||
|
||||
MkDocs is a Python package when turns your docs directory and YAML config into a static website. No Python coding needed. Just Markdown and some light configuration including a theme choice and menu.
|
||||
|
||||
<!-- TODO When creating a new project copied from this template, you can delete this README.md and start over -->
|
||||
|
||||
|
||||
## Purpose
|
||||
|
||||
This project provides low-code content-focused way to set up and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.
|
||||
|
||||
A GitHub Actions workflow is provided with this template so you can easily deploy to GitHub Pages too.
|
||||
|
||||
|
||||
## Preview
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://michaelcurrin.github.io/mkdocs-quickstart/ "Sample screenshot")
|
||||
|
||||
</div>
|
||||
|
||||
This template project is configured to use the _Read the Docs_ theme, as shown above.
|
||||
|
||||
Thus looks like the the [Read The Docs][] site, but without having to have to overhead of using Sphinx.
|
||||
|
||||
[Read The Docs]: https://docs.readthedocs.io
|
||||
|
||||
This Read the Docs theme for MkDocs comes with MkDocs already, so you don't need to add to your dependencies. But you can switch to the MkDocs default or install and configure another theme.
|
||||
|
||||
You can switch to the default theme or install some others, based on the instructions in this template project.
|
||||
|
||||
|
||||
## How to use this project
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://michaelcurrin.github.io/mkdocs-quickstart/)
|
||||
|
||||
[](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
- A **markdown-based** docs site which is easy to edit - see the content in the [docs](/docs/docs/) directory.
|
||||
- Easy to **configure** - see the short [mkdocs.yml](/docs/mkdocs.yml) file.
|
||||
- Use the configured theme or switch to another - no need to write HTML and CSS yourself.
|
||||
- Each theme comes with a navbar and you write YAML - Jekyll themes on GH Pages need you to write your own HTML often and each theme handles navbar its own way (sometimes not at all).
|
||||
- Uses a deploy pipeline on GH Actions to deploy a GH Pages site - the action actually runs GH Pages deploy command.
|
||||
- The static site output is **SEO-friendly**.
|
||||
- Built on Python but you don't need to write any Python code.
|
||||
|
||||
### View live demo site
|
||||
|
||||
This project has a site deployed to GitHub Pages.
|
||||
|
||||
Purposes of the site:
|
||||
|
||||
- A live demo.
|
||||
- Content for a beginner-friendly tutorial on how to setup, run, deploy and customize a MkDocs project like this one.
|
||||
|
||||
### Use this template
|
||||
|
||||
This repo also doubles as a template to create a new project from. Click the button at the top.
|
||||
|
||||
Change the content and theme to suit your needs, based on the tutorial site or the MkDocs site.
|
||||
|
||||
To isolate the MkDocs flow from the rest of your code, you can put the configs and the `docs` folder of content inside the `docs` directory. That means you end up having `docs/docs`, which is okay. Just make sure you select the `/docs` directory when setting up GH Pages.
|
||||
|
||||
|
||||
## About MkDocs
|
||||
|
||||
### Resources
|
||||
|
||||
- Homepage: [mkdocs.org](http://www.mkdocs.org/)
|
||||
- Repo: [](https://github.com/mkdocs/mkdocs) [](https://github.com/mkdocs/mkdocs)
|
||||
- PyPI package: [mkdocs](https://pypi.org/project/mkdocs/)
|
||||
|
||||
### Why MkDocs?
|
||||
|
||||
If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs homepage for documentation.
|
||||
|
||||
This project provides a way to write your docs in markdown and build a professional-looking docs site on top of it, without having to write HTML or CSS code and using a selection of themes. While MkDocs CLI has functionality to deploy from a local command-line, this project makes deploying effortless by using GitHub Actions to build and deploy the site to a `gh-pages` branch and GitHub Pages to serve the site.
|
||||
|
||||
Compared with Jekyll and Docsify, I found the MkDocs code is much lighter to set up and changing themes is much easier than Jekyll. Also you get the benefits SEO which Docsify doesn't have. And it includes a search bar using JS.
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
Submit an issue.
|
||||
|
||||
Or submit a code change:
|
||||
|
||||
1. Fork this project.
|
||||
2. Set up the project locally - follow the instructions on the live tutorial or in the [TL;DR](/docs/docs/tutorial/tldr.md) page of the local docs.
|
||||
3. Make any changes you want. Be sure to keep a copy of the original license in the repo.
|
||||
- e.g. `cp LICENSE LICENSE-source`
|
||||
4. Create a Pull Request.
|
||||
|
||||
|
||||
## License
|
||||
|
||||
Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).
|
||||
@@ -1,212 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/about-mkdocs/">
|
||||
<link rel="shortcut icon" href="../img/favicon.ico">
|
||||
<title>About MkDocs - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../css/theme.css" />
|
||||
<link rel="stylesheet" href="../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "About MkDocs";
|
||||
var mkdocs_page_input_path = "about-mkdocs.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/about-mkdocs/";
|
||||
</script>
|
||||
|
||||
<script src="../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href=".." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">About MkDocs</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#what-is-mkdocs">What is MkDocs?</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#resources">Resources</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#reasons-to-use-mkdocs">Reasons to use MkDocs</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#do-i-need-to-know-python">Do I need to know Python?</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tutorial/tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tutorial/installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tutorial/setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tutorial/advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tutorial/usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tutorial/deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>About MkDocs</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/about-mkdocs.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="about-mkdocs">About MkDocs</h1>
|
||||
<h2 id="what-is-mkdocs">What is MkDocs?</h2>
|
||||
<p>The description on the MkDocs site is:</p>
|
||||
<blockquote>
|
||||
<p>Project documentation with Markdown.</p>
|
||||
</blockquote>
|
||||
<p>MkDocs is a Python tool that generates a static site based on content written in Markdown.</p>
|
||||
<p>If you are new to markdown, see the <a href="https://www.markdownguide.org/getting-started/">Getting Started</a> page on the Markdown Guide website.</p>
|
||||
<h2 id="resources">Resources</h2>
|
||||
<ul>
|
||||
<li><a href="https://www.mkdocs.org">mkdocs.org</a> homepage</li>
|
||||
<li><a href="https://github.com/mkdocs/mkdocs">mkdocs/mkdocs <img alt="Repo stars" src="https://img.shields.io/github/stars/mkdocs/mkdocs?style=social" /></a></li>
|
||||
<li><a href="https://github.com/mkdocs/mkdocs/wiki">MkDocs Wiki</a> - covering themes, plugins, recipes and more.</li>
|
||||
<li><a href="https://www.mkdocs.org/about/release-notes/">Release notes</a> for MkDocs.</li>
|
||||
</ul>
|
||||
<h2 id="reasons-to-use-mkdocs">Reasons to use MkDocs</h2>
|
||||
<ul>
|
||||
<li>Create an elegant, modern docs site for your project.</li>
|
||||
<li>Create a static site and serve from GitHub Pages easily.</li>
|
||||
<li>Low-code solution<ul>
|
||||
<li>No need to write HTML or learn templating syntax needed</li>
|
||||
<li>Use your existing markdown files as content.</li>
|
||||
<li>Configure with a simple YAML file.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Customizable.<ul>
|
||||
<li>Add custom HTML if you want.</li>
|
||||
<li>Plugins available.</li>
|
||||
<li>Flexible theme choices.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Includes search by default.</li>
|
||||
<li>Broken links to files (including from your navbar) will be detected at build time and shown as warnings.</li>
|
||||
</ul>
|
||||
<h2 id="do-i-need-to-know-python">Do I need to know Python?</h2>
|
||||
<p>MkDocs is built in Python (like Sphinx), but you don't have to write Python code. If you set up a <a href="deploy">Deploy</a> flow right, you don't even have to set it up locally, though then you can't preview.</p>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="../tutorial/tldr/" class="btn btn-neutral float-right" title="TL;DR">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
<a href=".." class="btn btn-neutral" title="Home"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href=".." style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
<span><a href="../tutorial/tldr/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '..';</script>
|
||||
<script src="../js/theme_extra.js" defer></script>
|
||||
<script src="../js/theme.js" defer></script>
|
||||
<script src="../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because one or more lines are too long
@@ -1,191 +0,0 @@
|
||||
/*
|
||||
* Wrap inline code samples otherwise they shoot of the side and
|
||||
* can't be read at all.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/313
|
||||
* https://github.com/mkdocs/mkdocs/issues/233
|
||||
* https://github.com/mkdocs/mkdocs/issues/834
|
||||
*/
|
||||
.rst-content code {
|
||||
white-space: pre-wrap;
|
||||
word-wrap: break-word;
|
||||
padding: 2px 5px;
|
||||
}
|
||||
|
||||
/**
|
||||
* Make code blocks display as blocks and give them the appropriate
|
||||
* font size and padding.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/855
|
||||
* https://github.com/mkdocs/mkdocs/issues/834
|
||||
* https://github.com/mkdocs/mkdocs/issues/233
|
||||
*/
|
||||
.rst-content pre code {
|
||||
white-space: pre;
|
||||
word-wrap: normal;
|
||||
display: block;
|
||||
padding: 12px;
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fix code colors
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/2027
|
||||
*/
|
||||
.rst-content code {
|
||||
color: #E74C3C;
|
||||
}
|
||||
|
||||
.rst-content pre code {
|
||||
color: #000;
|
||||
background: #f8f8f8;
|
||||
}
|
||||
|
||||
/*
|
||||
* Fix link colors when the link text is inline code.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/718
|
||||
*/
|
||||
a code {
|
||||
color: #2980B9;
|
||||
}
|
||||
a:hover code {
|
||||
color: #3091d1;
|
||||
}
|
||||
a:visited code {
|
||||
color: #9B59B6;
|
||||
}
|
||||
|
||||
/*
|
||||
* The CSS classes from highlight.js seem to clash with the
|
||||
* ReadTheDocs theme causing some code to be incorrectly made
|
||||
* bold and italic.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/411
|
||||
*/
|
||||
pre .cs, pre .c {
|
||||
font-weight: inherit;
|
||||
font-style: inherit;
|
||||
}
|
||||
|
||||
/*
|
||||
* Fix some issues with the theme and non-highlighted code
|
||||
* samples. Without and highlighting styles attached the
|
||||
* formatting is broken.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/319
|
||||
*/
|
||||
.rst-content .no-highlight {
|
||||
display: block;
|
||||
padding: 0.5em;
|
||||
color: #333;
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* Additions specific to the search functionality provided by MkDocs
|
||||
*/
|
||||
|
||||
.search-results {
|
||||
margin-top: 23px;
|
||||
}
|
||||
|
||||
.search-results article {
|
||||
border-top: 1px solid #E1E4E5;
|
||||
padding-top: 24px;
|
||||
}
|
||||
|
||||
.search-results article:first-child {
|
||||
border-top: none;
|
||||
}
|
||||
|
||||
form .search-query {
|
||||
width: 100%;
|
||||
border-radius: 50px;
|
||||
padding: 6px 12px; /* csslint allow: box-model */
|
||||
border-color: #D1D4D5;
|
||||
}
|
||||
|
||||
/*
|
||||
* Improve inline code blocks within admonitions.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/656
|
||||
*/
|
||||
.rst-content .admonition code {
|
||||
color: #404040;
|
||||
border: 1px solid #c7c9cb;
|
||||
border: 1px solid rgba(0, 0, 0, 0.2);
|
||||
background: #f8fbfd;
|
||||
background: rgba(255, 255, 255, 0.7);
|
||||
}
|
||||
|
||||
/*
|
||||
* Account for wide tables which go off the side.
|
||||
* Override borders to avoid wierdness on narrow tables.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/834
|
||||
* https://github.com/mkdocs/mkdocs/pull/1034
|
||||
*/
|
||||
.rst-content .section .docutils {
|
||||
width: 100%;
|
||||
overflow: auto;
|
||||
display: block;
|
||||
border: none;
|
||||
}
|
||||
|
||||
td, th {
|
||||
border: 1px solid #e1e4e5 !important; /* csslint allow: important */
|
||||
border-collapse: collapse;
|
||||
}
|
||||
|
||||
/*
|
||||
* Without the following amendments, the navigation in the theme will be
|
||||
* slightly cut off. This is due to the fact that the .wy-nav-side has a
|
||||
* padding-bottom of 2em, which must not necessarily align with the font-size of
|
||||
* 90 % on the .rst-current-version container, combined with the padding of 12px
|
||||
* above and below. These amendments fix this in two steps: First, make sure the
|
||||
* .rst-current-version container has a fixed height of 40px, achieved using
|
||||
* line-height, and then applying a padding-bottom of 40px to this container. In
|
||||
* a second step, the items within that container are re-aligned using flexbox.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/2012
|
||||
*/
|
||||
.wy-nav-side {
|
||||
padding-bottom: 40px;
|
||||
}
|
||||
|
||||
/*
|
||||
* The second step of above amendment: Here we make sure the items are aligned
|
||||
* correctly within the .rst-current-version container. Using flexbox, we
|
||||
* achieve it in such a way that it will look like the following:
|
||||
*
|
||||
* [No repo_name]
|
||||
* Next >> // On the first page
|
||||
* << Previous Next >> // On all subsequent pages
|
||||
*
|
||||
* [With repo_name]
|
||||
* <repo_name> Next >> // On the first page
|
||||
* <repo_name> << Previous Next >> // On all subsequent pages
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/2012
|
||||
*/
|
||||
.rst-versions .rst-current-version {
|
||||
padding: 0 12px;
|
||||
display: flex;
|
||||
font-size: initial;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
line-height: 40px;
|
||||
}
|
||||
|
||||
/*
|
||||
* Please note that this amendment also involves removing certain inline-styles
|
||||
* from the file ./mkdocs/themes/readthedocs/versions.html.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/2012
|
||||
*/
|
||||
.rst-current-version span {
|
||||
flex: 1;
|
||||
text-align: center;
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
.PHONY: docs
|
||||
|
||||
default: install
|
||||
|
||||
all: install build
|
||||
|
||||
|
||||
h help:
|
||||
@grep '^[a-z]' Makefile
|
||||
|
||||
|
||||
install:
|
||||
pip install pip --upgrade
|
||||
pip install -r requirements.txt
|
||||
|
||||
upgrade:
|
||||
pip install pip --upgrade
|
||||
pip install -r requirements.txt --upgrade
|
||||
|
||||
|
||||
s serve:
|
||||
mkdocs serve --strict
|
||||
|
||||
|
||||
b build:
|
||||
mkdocs build --strict
|
||||
|
||||
d deploy:
|
||||
mkdocs gh-deploy --strict --force
|
||||
@@ -0,0 +1,41 @@
|
||||
# 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](https://www.markdownguide.org/getting-started/) page on the Markdown Guide website.
|
||||
|
||||
|
||||
## Resources
|
||||
|
||||
- [mkdocs.org](https://www.mkdocs.org) homepage
|
||||
- [mkdocs/mkdocs ](https://github.com/mkdocs/mkdocs)
|
||||
- [MkDocs Wiki](https://github.com/mkdocs/mkdocs/wiki) - covering themes, plugins, recipes and more.
|
||||
- [Release notes](https://www.mkdocs.org/about/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](deploy) flow right, you don't even have to set it up locally, though then you can't preview.
|
||||
@@ -0,0 +1,26 @@
|
||||
# MkDocs Quickstart
|
||||
> Started template for a MkDocs docs site on GH Pages - including CI
|
||||
|
||||
[](https://github.com/MichaelCurrin/mkdocs-quickstart)
|
||||
|
||||
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**
|
||||
- [](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
|
||||
- **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](https://www.mkdocs.org/) tutorial.
|
||||
@@ -0,0 +1,53 @@
|
||||
# Advanced
|
||||
> Beyond the basic configuration and content
|
||||
|
||||
Once you've got the [Set up Project](setup-project.md) section, you can customize further using this guide. Or skip this and go to [Usage](usage.md).
|
||||
|
||||
|
||||
## Navbar nesting
|
||||
|
||||
You can add an additional level to your navbar like this:
|
||||
|
||||
```yaml
|
||||
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](https://github.com/mkdocs/mkdocs/issues/1139).
|
||||
|
||||
|
||||
## Add config options
|
||||
|
||||
See [Configuration](https://www.mkdocs.org/user-guide/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](https://github.com/python-poetry/poetry/tree/master/docs) 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.
|
||||
|
||||
```html
|
||||
<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
|
||||
```
|
||||
@@ -0,0 +1,59 @@
|
||||
# Deploy
|
||||
> Build and deploy to a remote public site
|
||||
|
||||
|
||||
See [Deploying Your Docs](https://www.mkdocs.org/user-guide/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-deploy-command) - Run a MkDocs CLI command locally to deploy.
|
||||
- [Deploy with GitHub Actions](#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:
|
||||
|
||||
```sh
|
||||
$ make d
|
||||
```
|
||||
|
||||
That will use `Makefile` to run the following:
|
||||
|
||||
```sh
|
||||
$ mkdocs gh-deploy --strict --force
|
||||
```
|
||||
|
||||
That will do the following:
|
||||
|
||||
1. Clean and build to `site` directory.
|
||||
2. 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/](https://michaelcurrin.github.io/mkdocs-quickstart/)
|
||||
|
||||
See deploy options in the help:
|
||||
|
||||
```sh
|
||||
$ 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](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/.github/workflows/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.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Installation
|
||||
> How to install MkDocs locally.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Python 3](https://www.python.org/)
|
||||
- [Make](https://www.gnu.org/software/make/) - standard on macOS and Linux but can be installed on Windows too.
|
||||
|
||||
|
||||
## Install system dependencies
|
||||
|
||||
<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
[](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
|
||||
|
||||
Then clone your repo.
|
||||
|
||||
e.g.
|
||||
|
||||
```sh
|
||||
$ git clone git@github.com:MichaelCurrin/mkdocs-quickstart.git
|
||||
$ cd mkdocs-quickstart
|
||||
```
|
||||
|
||||
|
||||
## Install project dependencies
|
||||
> Install MkDocs locally
|
||||
|
||||
For more info, see the [Installation](https://www.mkdocs.org/#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.
|
||||
|
||||
```sh
|
||||
$ python3 -m venv venv
|
||||
```
|
||||
|
||||
Activate the environment.
|
||||
|
||||
```sh
|
||||
$ source venv/bin/activate
|
||||
```
|
||||
|
||||
Install `mkdocs` - this is covered in the project requirements file.
|
||||
|
||||
```sh
|
||||
$ cd docs
|
||||
$ make install
|
||||
```
|
||||
|
||||
Note - `mkdocs` 1.2 causes a break on force pushes, so this is excluded in the requirements. See issue [#2447](https://github.com/mkdocs/mkdocs/issues/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:
|
||||
|
||||
```sh
|
||||
$ python3 -m pip install mkdocs
|
||||
```
|
||||
|
||||
If you get prompted for `sudo` use, then cancel and run again with `-U` flag for user-level install.
|
||||
@@ -0,0 +1,150 @@
|
||||
# Set up project
|
||||
> How to create a MkDocs site from scratch
|
||||
|
||||
This is a summary of the tutorial on [mkdocs.org](https://www.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](#create-a-starter-site).
|
||||
- Follow the extended guide to create a [Set up up docs site](#setup-a-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](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/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](https://www.mkdocs.org/user-guide/configuration/#repo_url).
|
||||
- `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](https://www.mkdocs.org/user-guide/configuration/#edit_uri)
|
||||
|
||||
### 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.
|
||||
|
||||
```sh
|
||||
cd my-project
|
||||
mkdocs new PATH
|
||||
```
|
||||
|
||||
The result will be same as the [Basic structure](#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](https://github.com/mkdocs/mkdocs/blob/master/mkdocs/commands/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_.
|
||||
|
||||
1. Create doc pages.
|
||||
1. Create a `docs` directory.
|
||||
2. Create `index.md` as your homepage.
|
||||
3. 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.
|
||||
2. Set up config.
|
||||
1. Create `mkdocs.yml` at the project root.
|
||||
2. Set up a navbar there.
|
||||
3. Choose a theme.
|
||||
3. Create a favicon (optional).
|
||||
- It will be picked up at this path: `docs/img/favicon.ico`.
|
||||
4. 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`
|
||||
```yaml
|
||||
nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
```
|
||||
|
||||
### Themes
|
||||
|
||||
#### Builtin
|
||||
|
||||
Use a builtin theme that comes with MkDocs.
|
||||
|
||||
The default.
|
||||
|
||||
```yaml
|
||||
theme: mkdocs
|
||||
```
|
||||
|
||||
Using ReadTheDocs theme and alternative config syntax.
|
||||
|
||||
```yaml
|
||||
theme:
|
||||
name: readthedocs
|
||||
```
|
||||
|
||||
Find more [supported themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-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](https://github.com/cjsheets/mkdocs-rtd-dropdown).
|
||||
|
||||
`requirements.txt`:
|
||||
```
|
||||
mkdocs-rtd-dropdown
|
||||
```
|
||||
|
||||
`mkdocs.yml`:
|
||||
|
||||
```yaml
|
||||
theme:
|
||||
name: 'rtd-dropdown'
|
||||
```
|
||||
|
||||
### Material for MkdDocs theme
|
||||
|
||||
See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Set up page for config options.
|
||||
|
||||
`requirements.txt`:
|
||||
```
|
||||
mkdocs-material-extensions>=1.0
|
||||
```
|
||||
|
||||
`mkdocs.yml`:
|
||||
```yaml
|
||||
theme:
|
||||
name: 'material'
|
||||
```
|
||||
@@ -0,0 +1,28 @@
|
||||
# TL;DR
|
||||
> A simplified version of the tutorial.
|
||||
|
||||
|
||||
## Local setup
|
||||
|
||||
1. [Install](installation.md)
|
||||
- `pip install mkdocs`
|
||||
2. [Set up project](setup-project.md)
|
||||
- `mkdocs new .` or [](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
|
||||
3. [Run](usage.md)
|
||||
- `mkdocs serve`
|
||||
4. View on [localhost:8000](http://localhost:8000)
|
||||
|
||||
|
||||
## Deploy to remote site
|
||||
|
||||
### Run deploy command locally
|
||||
|
||||
1. [Deploy](deploy.md) to GitHub Pages
|
||||
- `mkdocs gh-deploy`
|
||||
2. 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](https://github.com/marketplace/actions/deploy-mkdocs). Or use Netlify.
|
||||
|
||||
This is not covered in this tutorial.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Usage
|
||||
> Build and preview a site locally
|
||||
|
||||
Make sure to run all commands from the `docs` directory, as that is where `Makefile` is.
|
||||
|
||||
```sh
|
||||
$ cd docs
|
||||
```
|
||||
|
||||
|
||||
## CLI help
|
||||
|
||||
```sh
|
||||
$ 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.
|
||||
|
||||
```sh
|
||||
$ make serve
|
||||
```
|
||||
|
||||
Then open in your browser:
|
||||
|
||||
- [localhost:8000](http://localhost:8000)
|
||||
|
||||
|
||||
## Build docs
|
||||
|
||||
Build docs site to `site` directory. This is useful for a CI flow.
|
||||
|
||||
```sh
|
||||
$ make build
|
||||
```
|
||||
@@ -0,0 +1,23 @@
|
||||
### Site metadata ###
|
||||
|
||||
site_name: MkDocs Quickstart
|
||||
site_description: Starter template for a MkDocs docs site on GH Pages - including CI
|
||||
site_url: https://michaelcurrin.github.io/mkdocs-quickstart/
|
||||
|
||||
repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart
|
||||
edit_uri: edit/master/docs/docs
|
||||
|
||||
### Build settings ###
|
||||
|
||||
theme: readthedocs
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- About MkDocs: about-mkdocs.md
|
||||
- Tutorial:
|
||||
- TL;DR: tutorial/tldr.md
|
||||
- Installation: tutorial/installation.md
|
||||
- Set up project: tutorial/setup-project.md
|
||||
- Advanced: tutorial/advanced.md
|
||||
- Usage: tutorial/usage.md
|
||||
- Deploy: tutorial/deploy.md
|
||||
@@ -0,0 +1 @@
|
||||
mkdocs~=1.1,!=1.2
|
||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
File diff suppressed because it is too large
Load Diff
|
Before Width: | Height: | Size: 434 KiB |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 KiB |
-200
@@ -1,200 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="description" content="Starter template for a MkDocs docs site on GH Pages - including CI">
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/">
|
||||
<link rel="shortcut icon" href="img/favicon.ico">
|
||||
<title>MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="css/theme.css" />
|
||||
<link rel="stylesheet" href="css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "Home";
|
||||
var mkdocs_page_input_path = "index.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/";
|
||||
</script>
|
||||
|
||||
<script src="js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="./search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href=".">Home</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#features">Features</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="tutorial/tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="tutorial/installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="tutorial/setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="tutorial/advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="tutorial/usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="tutorial/deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href=".">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href=".">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Home</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/index.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="mkdocs-quickstart">MkDocs Quickstart</h1>
|
||||
<blockquote>
|
||||
<p>Started template for a MkDocs docs site on GH Pages - including CI </p>
|
||||
</blockquote>
|
||||
<p><a href="https://github.com/MichaelCurrin/mkdocs-quickstart"><img alt="Repo stars" src="https://img.shields.io/github/stars/MichaelCurrin/mkdocs-quickstart?style=social" /></a></p>
|
||||
<p>Use the MkDocs (<em>make docs</em>) tool to create build a docs site around markdown docs.</p>
|
||||
<p>Follow the tutorial to add an existing project or create a project from scratch. The result will look like this project.</p>
|
||||
<h2 id="features">Features</h2>
|
||||
<blockquote>
|
||||
<p>How to use this project</p>
|
||||
</blockquote>
|
||||
<ul>
|
||||
<li><strong>Follow the tutorial instructions</strong><ul>
|
||||
<li>Install and configure a new or existing project.</li>
|
||||
<li>Run it locally.</li>
|
||||
<li>Deploy it.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Add a copy of this project to your repos</strong><ul>
|
||||
<li><a href="https://github.com/MichaelCurrin/mkdocs-quickstart/generate"><img alt="Use this template" src="https://img.shields.io/badge/Use_this_template-2ea44f?logo=github" /></a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>View the live demo</strong><ul>
|
||||
<li>This site is hosted on GitHub Pages. See if you like it. Other themes are available - see the tutorial.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>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.</p>
|
||||
<p>This guide is based on the <a href="https://www.mkdocs.org/">mkdocs.org</a> tutorial.</p>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="about-mkdocs/" class="btn btn-neutral float-right" title="About MkDocs">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
<span><a href="about-mkdocs/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '.';</script>
|
||||
<script src="js/theme_extra.js" defer></script>
|
||||
<script src="js/theme.js" defer></script>
|
||||
<script src="search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
<!--
|
||||
MkDocs version : 1.2.2
|
||||
Build Date UTC : 2021-07-28 11:07:01.106767+00:00
|
||||
-->
|
||||
Vendored
-4
File diff suppressed because one or more lines are too long
Vendored
-1
File diff suppressed because one or more lines are too long
@@ -1,3 +0,0 @@
|
||||
/* sphinx_rtd_theme version 0.4.1 | MIT license */
|
||||
/* Built 20180727 10:07 */
|
||||
require=function n(e,i,t){function o(s,a){if(!i[s]){if(!e[s]){var l="function"==typeof require&&require;if(!a&&l)return l(s,!0);if(r)return r(s,!0);var c=new Error("Cannot find module '"+s+"'");throw c.code="MODULE_NOT_FOUND",c}var u=i[s]={exports:{}};e[s][0].call(u.exports,function(n){var i=e[s][1][n];return o(i||n)},u,u.exports,n,e,i,t)}return i[s].exports}for(var r="function"==typeof require&&require,s=0;s<t.length;s++)o(t[s]);return o}({"sphinx-rtd-theme":[function(n,e,i){var jQuery="undefined"!=typeof window?window.jQuery:n("jquery");e.exports.ThemeNav={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1,enable:function(n){var e=this;void 0===n&&(n=!0),e.isRunning||(e.isRunning=!0,jQuery(function(i){e.init(i),e.reset(),e.win.on("hashchange",e.reset),n&&e.win.on("scroll",function(){e.linkScroll||e.winScroll||(e.winScroll=!0,requestAnimationFrame(function(){e.onScroll()}))}),e.win.on("resize",function(){e.winResize||(e.winResize=!0,requestAnimationFrame(function(){e.onResize()}))}),e.onResize()}))},enableSticky:function(){this.enable(!0)},init:function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")}).on("click",".wy-menu-vertical .current ul li a",function(){var i=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(i),e.hashChange()}).on("click","[data-toggle='rst-current-version']",function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")}),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("<div class='wy-table-responsive'></div>"),n("table.docutils.footnote").wrap("<div class='wy-table-responsive footnote'></div>"),n("table.docutils.citation").wrap("<div class='wy-table-responsive citation'></div>"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each(function(){var i=n(this);expand=n('<span class="toctree-expand"></span>'),expand.on("click",function(n){return e.toggleCurrent(i),n.stopPropagation(),!1}),i.prepend(expand)})},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),i=e.find('[href="'+n+'"]');if(0===i.length){var t=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(i=e.find('[href="#'+t.attr("id")+'"]')).length&&(i=e.find('[href="#"]'))}i.length>0&&($(".wy-menu-vertical .current").removeClass("current"),i.addClass("current"),i.closest("li.toctree-l1").addClass("current"),i.closest("li.toctree-l1").parent().addClass("current"),i.closest("li.toctree-l1").addClass("current"),i.closest("li.toctree-l2").addClass("current"),i.closest("li.toctree-l3").addClass("current"),i.closest("li.toctree-l4").addClass("current"))}catch(o){console.log("Error expanding nav for anchor",o)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,i=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(i),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",function(){this.linkScroll=!1})},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current"),e.siblings().find("li.current").removeClass("current"),e.find("> ul li.current").removeClass("current"),e.toggleClass("current")}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:e.exports.ThemeNav,StickyNav:e.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],i=0;i<e.length&&!window.requestAnimationFrame;++i)window.requestAnimationFrame=window[e[i]+"RequestAnimationFrame"],window.cancelAnimationFrame=window[e[i]+"CancelAnimationFrame"]||window[e[i]+"CancelRequestAnimationFrame"];window.requestAnimationFrame||(window.requestAnimationFrame=function(e,i){var t=(new Date).getTime(),o=Math.max(0,16-(t-n)),r=window.setTimeout(function(){e(t+o)},o);return n=t+o,r}),window.cancelAnimationFrame||(window.cancelAnimationFrame=function(n){clearTimeout(n)})}()},{jquery:"jquery"}]},{},["sphinx-rtd-theme"]);
|
||||
@@ -1,8 +0,0 @@
|
||||
/*
|
||||
* Assign 'docutils' class to tables so styling and
|
||||
* JavaScript behavior is applied.
|
||||
*
|
||||
* https://github.com/mkdocs/mkdocs/issues/2028
|
||||
*/
|
||||
|
||||
$('div.rst-content table').addClass('docutils');
|
||||
BIN
Binary file not shown.
|
After Width: | Height: | Size: 335 KiB |
-153
@@ -1,153 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
|
||||
<link rel="shortcut icon" href="./img/favicon.ico">
|
||||
<title>MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="./css/theme.css" />
|
||||
<link rel="stylesheet" href="./css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script src="./js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="./js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="./." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="./search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./.">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./tutorial/tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./tutorial/installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./tutorial/setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./tutorial/advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./tutorial/usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="./tutorial/deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="./.">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="./.">Docs</a> »</li>
|
||||
|
||||
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
|
||||
<h1 id="search">Search Results</h1>
|
||||
|
||||
<form id="content_search" action="search.html">
|
||||
<span role="status" aria-live="polite" class="ui-helper-hidden-accessible"></span>
|
||||
<input name="q" id="mkdocs-search-query" type="text" class="search_input search-query ui-autocomplete-input" placeholder="Search the Docs" autocomplete="off" autofocus title="Type search term here">
|
||||
</form>
|
||||
|
||||
<div id="mkdocs-search-results" class="search-results" data-no-results-text="No results found">
|
||||
Searching...
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '.';</script>
|
||||
<script src="./js/theme_extra.js" defer></script>
|
||||
<script src="./js/theme.js" defer></script>
|
||||
<script src="./search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
-3475
File diff suppressed because it is too large
Load Diff
-102
@@ -1,102 +0,0 @@
|
||||
function getSearchTermFromLocation() {
|
||||
var sPageURL = window.location.search.substring(1);
|
||||
var sURLVariables = sPageURL.split('&');
|
||||
for (var i = 0; i < sURLVariables.length; i++) {
|
||||
var sParameterName = sURLVariables[i].split('=');
|
||||
if (sParameterName[0] == 'q') {
|
||||
return decodeURIComponent(sParameterName[1].replace(/\+/g, '%20'));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function joinUrl (base, path) {
|
||||
if (path.substring(0, 1) === "/") {
|
||||
// path starts with `/`. Thus it is absolute.
|
||||
return path;
|
||||
}
|
||||
if (base.substring(base.length-1) === "/") {
|
||||
// base ends with `/`
|
||||
return base + path;
|
||||
}
|
||||
return base + "/" + path;
|
||||
}
|
||||
|
||||
function formatResult (location, title, summary) {
|
||||
return '<article><h3><a href="' + joinUrl(base_url, location) + '">'+ title + '</a></h3><p>' + summary +'</p></article>';
|
||||
}
|
||||
|
||||
function displayResults (results) {
|
||||
var search_results = document.getElementById("mkdocs-search-results");
|
||||
while (search_results.firstChild) {
|
||||
search_results.removeChild(search_results.firstChild);
|
||||
}
|
||||
if (results.length > 0){
|
||||
for (var i=0; i < results.length; i++){
|
||||
var result = results[i];
|
||||
var html = formatResult(result.location, result.title, result.summary);
|
||||
search_results.insertAdjacentHTML('beforeend', html);
|
||||
}
|
||||
} else {
|
||||
var noResultsText = search_results.getAttribute('data-no-results-text');
|
||||
if (!noResultsText) {
|
||||
noResultsText = "No results found";
|
||||
}
|
||||
search_results.insertAdjacentHTML('beforeend', '<p>' + noResultsText + '</p>');
|
||||
}
|
||||
}
|
||||
|
||||
function doSearch () {
|
||||
var query = document.getElementById('mkdocs-search-query').value;
|
||||
if (query.length > min_search_length) {
|
||||
if (!window.Worker) {
|
||||
displayResults(search(query));
|
||||
} else {
|
||||
searchWorker.postMessage({query: query});
|
||||
}
|
||||
} else {
|
||||
// Clear results for short queries
|
||||
displayResults([]);
|
||||
}
|
||||
}
|
||||
|
||||
function initSearch () {
|
||||
var search_input = document.getElementById('mkdocs-search-query');
|
||||
if (search_input) {
|
||||
search_input.addEventListener("keyup", doSearch);
|
||||
}
|
||||
var term = getSearchTermFromLocation();
|
||||
if (term) {
|
||||
search_input.value = term;
|
||||
doSearch();
|
||||
}
|
||||
}
|
||||
|
||||
function onWorkerMessage (e) {
|
||||
if (e.data.allowSearch) {
|
||||
initSearch();
|
||||
} else if (e.data.results) {
|
||||
var results = e.data.results;
|
||||
displayResults(results);
|
||||
} else if (e.data.config) {
|
||||
min_search_length = e.data.config.min_search_length-1;
|
||||
}
|
||||
}
|
||||
|
||||
if (!window.Worker) {
|
||||
console.log('Web Worker API not supported');
|
||||
// load index in main thread
|
||||
$.getScript(joinUrl(base_url, "search/worker.js")).done(function () {
|
||||
console.log('Loaded worker');
|
||||
init();
|
||||
window.postMessage = function (msg) {
|
||||
onWorkerMessage({data: msg});
|
||||
};
|
||||
}).fail(function (jqxhr, settings, exception) {
|
||||
console.error('Could not load worker.js');
|
||||
});
|
||||
} else {
|
||||
// Wrap search in a web worker
|
||||
var searchWorker = new Worker(joinUrl(base_url, "search/worker.js"));
|
||||
searchWorker.postMessage({init: true});
|
||||
searchWorker.onmessage = onWorkerMessage;
|
||||
}
|
||||
File diff suppressed because one or more lines are too long
@@ -1,133 +0,0 @@
|
||||
var base_path = 'function' === typeof importScripts ? '.' : '/search/';
|
||||
var allowSearch = false;
|
||||
var index;
|
||||
var documents = {};
|
||||
var lang = ['en'];
|
||||
var data;
|
||||
|
||||
function getScript(script, callback) {
|
||||
console.log('Loading script: ' + script);
|
||||
$.getScript(base_path + script).done(function () {
|
||||
callback();
|
||||
}).fail(function (jqxhr, settings, exception) {
|
||||
console.log('Error: ' + exception);
|
||||
});
|
||||
}
|
||||
|
||||
function getScriptsInOrder(scripts, callback) {
|
||||
if (scripts.length === 0) {
|
||||
callback();
|
||||
return;
|
||||
}
|
||||
getScript(scripts[0], function() {
|
||||
getScriptsInOrder(scripts.slice(1), callback);
|
||||
});
|
||||
}
|
||||
|
||||
function loadScripts(urls, callback) {
|
||||
if( 'function' === typeof importScripts ) {
|
||||
importScripts.apply(null, urls);
|
||||
callback();
|
||||
} else {
|
||||
getScriptsInOrder(urls, callback);
|
||||
}
|
||||
}
|
||||
|
||||
function onJSONLoaded () {
|
||||
data = JSON.parse(this.responseText);
|
||||
var scriptsToLoad = ['lunr.js'];
|
||||
if (data.config && data.config.lang && data.config.lang.length) {
|
||||
lang = data.config.lang;
|
||||
}
|
||||
if (lang.length > 1 || lang[0] !== "en") {
|
||||
scriptsToLoad.push('lunr.stemmer.support.js');
|
||||
if (lang.length > 1) {
|
||||
scriptsToLoad.push('lunr.multi.js');
|
||||
}
|
||||
if (lang.includes("ja") || lang.includes("jp")) {
|
||||
scriptsToLoad.push('tinyseg.js');
|
||||
}
|
||||
for (var i=0; i < lang.length; i++) {
|
||||
if (lang[i] != 'en') {
|
||||
scriptsToLoad.push(['lunr', lang[i], 'js'].join('.'));
|
||||
}
|
||||
}
|
||||
}
|
||||
loadScripts(scriptsToLoad, onScriptsLoaded);
|
||||
}
|
||||
|
||||
function onScriptsLoaded () {
|
||||
console.log('All search scripts loaded, building Lunr index...');
|
||||
if (data.config && data.config.separator && data.config.separator.length) {
|
||||
lunr.tokenizer.separator = new RegExp(data.config.separator);
|
||||
}
|
||||
|
||||
if (data.index) {
|
||||
index = lunr.Index.load(data.index);
|
||||
data.docs.forEach(function (doc) {
|
||||
documents[doc.location] = doc;
|
||||
});
|
||||
console.log('Lunr pre-built index loaded, search ready');
|
||||
} else {
|
||||
index = lunr(function () {
|
||||
if (lang.length === 1 && lang[0] !== "en" && lunr[lang[0]]) {
|
||||
this.use(lunr[lang[0]]);
|
||||
} else if (lang.length > 1) {
|
||||
this.use(lunr.multiLanguage.apply(null, lang)); // spread operator not supported in all browsers: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Browser_compatibility
|
||||
}
|
||||
this.field('title');
|
||||
this.field('text');
|
||||
this.ref('location');
|
||||
|
||||
for (var i=0; i < data.docs.length; i++) {
|
||||
var doc = data.docs[i];
|
||||
this.add(doc);
|
||||
documents[doc.location] = doc;
|
||||
}
|
||||
});
|
||||
console.log('Lunr index built, search ready');
|
||||
}
|
||||
allowSearch = true;
|
||||
postMessage({config: data.config});
|
||||
postMessage({allowSearch: allowSearch});
|
||||
}
|
||||
|
||||
function init () {
|
||||
var oReq = new XMLHttpRequest();
|
||||
oReq.addEventListener("load", onJSONLoaded);
|
||||
var index_path = base_path + '/search_index.json';
|
||||
if( 'function' === typeof importScripts ){
|
||||
index_path = 'search_index.json';
|
||||
}
|
||||
oReq.open("GET", index_path);
|
||||
oReq.send();
|
||||
}
|
||||
|
||||
function search (query) {
|
||||
if (!allowSearch) {
|
||||
console.error('Assets for search still loading');
|
||||
return;
|
||||
}
|
||||
|
||||
var resultDocuments = [];
|
||||
var results = index.search(query);
|
||||
for (var i=0; i < results.length; i++){
|
||||
var result = results[i];
|
||||
doc = documents[result.ref];
|
||||
doc.summary = doc.text.substring(0, 200);
|
||||
resultDocuments.push(doc);
|
||||
}
|
||||
return resultDocuments;
|
||||
}
|
||||
|
||||
if( 'function' === typeof importScripts ) {
|
||||
onmessage = function (e) {
|
||||
if (e.data.init) {
|
||||
init();
|
||||
} else if (e.data.query) {
|
||||
postMessage({ results: search(e.data.query) });
|
||||
} else {
|
||||
console.error("Worker - Unrecognized message: " + e);
|
||||
}
|
||||
};
|
||||
}
|
||||
-43
@@ -1,43 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/about-mkdocs/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/advanced/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/deploy/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/installation/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/setup-project/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/tldr/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/usage/</loc>
|
||||
<lastmod>2021-07-28</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
</urlset>
|
||||
Binary file not shown.
@@ -1,221 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/advanced/">
|
||||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||||
<title>Advanced - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../../css/theme.css" />
|
||||
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "Advanced";
|
||||
var mkdocs_page_input_path = "tutorial/advanced.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/advanced/";
|
||||
</script>
|
||||
|
||||
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">Advanced</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#navbar-nesting">Navbar nesting</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#add-config-options">Add config options</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#separate-docs-directory-approach">Separate docs directory approach</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#embedding">Embedding</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Tutorial »</li>
|
||||
|
||||
|
||||
|
||||
<li>Advanced</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/advanced.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="advanced">Advanced</h1>
|
||||
<blockquote>
|
||||
<p>Beyond the basic configuration and content</p>
|
||||
</blockquote>
|
||||
<p>Once you've got the <a href="../setup-project/">Set up Project</a> section, you can customize further using this guide. Or skip this and go to <a href="../usage/">Usage</a>.</p>
|
||||
<h2 id="navbar-nesting">Navbar nesting</h2>
|
||||
<p>You can add an additional level to your navbar like this:</p>
|
||||
<pre><code class="language-yaml">nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
- Foo:
|
||||
- Overview: foo/index.md
|
||||
- Bar: foo/bar.md
|
||||
</code></pre>
|
||||
<p>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 <a href="https://github.com/mkdocs/mkdocs/issues/1139">issue #1139</a>.</p>
|
||||
<h2 id="add-config-options">Add config options</h2>
|
||||
<p>See <a href="https://www.mkdocs.org/user-guide/configuration/">Configuration</a> page on MkDocs site for options.</p>
|
||||
<h2 id="separate-docs-directory-approach">Separate docs directory approach</h2>
|
||||
<p>You can also structure your project to have the set up above nested inside a <code>docs</code> directory. This is useful you have a few other directories and you want to keep the project root clean.</p>
|
||||
<ul>
|
||||
<li><code>docs/</code><ul>
|
||||
<li><code>docs/</code><ul>
|
||||
<li><code>index.md</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>theme/</code><ul>
|
||||
<li><code>main.html</code></li>
|
||||
<li><code>nav.html</code></li>
|
||||
<li><code>toc.html</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>mkdocs.yml</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>An example of this is the <a href="https://github.com/python-poetry/poetry/tree/master/docs">Poetry</a> repo. That project is also how I got into MkDocs in the first place.</p>
|
||||
<h2 id="embedding">Embedding</h2>
|
||||
<p>To embed a gist, just copy and paste the embed script URL which is provided on a gist.</p>
|
||||
<p>e.g.</p>
|
||||
<pre><code class="language-html"><script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
|
||||
</code></pre>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="../usage/" class="btn btn-neutral float-right" title="Usage">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
<a href="../setup-project/" class="btn btn-neutral" title="Set up project"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href="../setup-project/" style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
<span><a href="../usage/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '../..';</script>
|
||||
<script src="../../js/theme_extra.js" defer></script>
|
||||
<script src="../../js/theme.js" defer></script>
|
||||
<script src="../../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,220 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/deploy/">
|
||||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||||
<title>Deploy - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../../css/theme.css" />
|
||||
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "Deploy";
|
||||
var mkdocs_page_input_path = "tutorial/deploy.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/deploy/";
|
||||
</script>
|
||||
|
||||
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">Deploy</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#github-pages">GitHub Pages</a>
|
||||
<ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#run-deploy-command">Run deploy command</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#deploy-with-github-actions">Deploy with GitHub Actions</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Tutorial »</li>
|
||||
|
||||
|
||||
|
||||
<li>Deploy</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/deploy.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="deploy">Deploy</h1>
|
||||
<blockquote>
|
||||
<p>Build and deploy to a remote public site</p>
|
||||
</blockquote>
|
||||
<p>See <a href="https://www.mkdocs.org/user-guide/deploying-your-docs/">Deploying Your Docs</a> on the Mkdocs site for more details.</p>
|
||||
<h2 id="github-pages">GitHub Pages</h2>
|
||||
<blockquote>
|
||||
<p>How to deploy your docs site to GitHub Pages.</p>
|
||||
</blockquote>
|
||||
<p>Follow one of the approaches below:</p>
|
||||
<ul>
|
||||
<li><a href="#run-deploy-command">Run deploy command</a> - Run a MkDocs CLI command locally to deploy.</li>
|
||||
<li><a href="#deploy-with-github-actions">Deploy with GitHub Actions</a> - Use the project's CI workflow in the cloud to build and deploy to GH Pages on commits pushed to master.</li>
|
||||
</ul>
|
||||
<p>Then go to your repo's <em>Settings</em> and <em>Pages</em> then enable <em>GitHub Pages</em> on the <code>gh-pages</code> branch's root.</p>
|
||||
<p><em>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.</em></p>
|
||||
<h3 id="run-deploy-command">Run deploy command</h3>
|
||||
<blockquote>
|
||||
<p>Run a MkDocs CLI command locally to deploy</p>
|
||||
</blockquote>
|
||||
<p>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 <code>remote</code> repo.</p>
|
||||
<p>Run this command locally:</p>
|
||||
<pre><code class="language-sh">$ make d
|
||||
</code></pre>
|
||||
<p>That will use <code>Makefile</code> to run the following:</p>
|
||||
<pre><code class="language-sh">$ mkdocs gh-deploy --strict --force
|
||||
</code></pre>
|
||||
<p>That will do the following:</p>
|
||||
<ol>
|
||||
<li>Clean and build to <code>site</code> directory.</li>
|
||||
<li>Force push to <code>gh-pages</code> branch, overwriting any changes which were pushed from another build.</li>
|
||||
</ol>
|
||||
<p>Then go to your repo on GitHub, look at the <em>Environment</em> tab.</p>
|
||||
<p>When it is done building, click <em>View deployment</em> to see your site.</p>
|
||||
<p>e.g. <a href="https://michaelcurrin.github.io/mkdocs-quickstart/">michaelcurrin.github.io/mkdocs-quickstart/</a></p>
|
||||
<p>See deploy options in the help:</p>
|
||||
<pre><code class="language-sh">$ mkdocs gh-deploy --help
|
||||
</code></pre>
|
||||
<h3 id="deploy-with-github-actions">Deploy with GitHub Actions</h3>
|
||||
<blockquote>
|
||||
<p>Set up continuous deployment config to enable deploys on a change to files on GitHub</p>
|
||||
</blockquote>
|
||||
<p>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.</p>
|
||||
<p>See the <a href="https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/.github/workflows/docs.yml">docs.yml</a> workflow provided with this project. You don't have to change anything there. The token will be generated for you by GitHub Actions.</p>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
|
||||
<a href="../usage/" class="btn btn-neutral" title="Usage"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href="../usage/" style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '../..';</script>
|
||||
<script src="../../js/theme_extra.js" defer></script>
|
||||
<script src="../../js/theme.js" defer></script>
|
||||
<script src="../../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,231 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/installation/">
|
||||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||||
<title>Installation - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../../css/theme.css" />
|
||||
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "Installation";
|
||||
var mkdocs_page_input_path = "tutorial/installation.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/installation/";
|
||||
</script>
|
||||
|
||||
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">Installation</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#install-system-dependencies">Install system dependencies</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#set-up-a-new-repo">Set up a new repo</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#install-project-dependencies">Install project dependencies</a>
|
||||
<ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#install-in-a-virtual-environment">Install in a virtual environment</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#install-globally">Install globally</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Tutorial »</li>
|
||||
|
||||
|
||||
|
||||
<li>Installation</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/installation.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="installation">Installation</h1>
|
||||
<blockquote>
|
||||
<p>How to install MkDocs locally.</p>
|
||||
</blockquote>
|
||||
<h2 id="requirements">Requirements</h2>
|
||||
<ul>
|
||||
<li><a href="https://www.python.org/">Python 3</a></li>
|
||||
<li><a href="https://www.gnu.org/software/make/">Make</a> - standard on macOS and Linux but can be installed on Windows too.</li>
|
||||
</ul>
|
||||
<h2 id="install-system-dependencies">Install system dependencies</h2>
|
||||
<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
|
||||
|
||||
<h2 id="set-up-a-new-repo">Set up a new repo</h2>
|
||||
<p>Follow the Tutorial page to set up a project from scratch.</p>
|
||||
<p>Or click this create your own copy of the repo.</p>
|
||||
<p><a href="https://github.com/MichaelCurrin/mkdocs-quickstart/generate"><img alt="Use this template" src="https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge&logo=github" /></a></p>
|
||||
<p>Then clone your repo.</p>
|
||||
<p>e.g.</p>
|
||||
<pre><code class="language-sh">$ git clone git@github.com:MichaelCurrin/mkdocs-quickstart.git
|
||||
$ cd mkdocs-quickstart
|
||||
</code></pre>
|
||||
<h2 id="install-project-dependencies">Install project dependencies</h2>
|
||||
<blockquote>
|
||||
<p>Install MkDocs locally</p>
|
||||
</blockquote>
|
||||
<p>For more info, see the <a href="https://www.mkdocs.org/#installation">Installation</a> page on the MkDocs site.</p>
|
||||
<h3 id="install-in-a-virtual-environment">Install in a virtual environment</h3>
|
||||
<p>Create a virtual environment at the project root - this is used to isolate project packages from the global packages.</p>
|
||||
<pre><code class="language-sh">$ python3 -m venv venv
|
||||
</code></pre>
|
||||
<p>Activate the environment.</p>
|
||||
<pre><code class="language-sh">$ source venv/bin/activate
|
||||
</code></pre>
|
||||
<p>Install <code>mkdocs</code> - this is covered in the project requirements file.</p>
|
||||
<pre><code class="language-sh">$ cd docs
|
||||
$ make install
|
||||
</code></pre>
|
||||
<p>Note - <code>mkdocs</code> 1.2 causes a break on force pushes, so this is excluded in the requirements. See issue <a href="https://github.com/mkdocs/mkdocs/issues/2447">#2447</a>.</p>
|
||||
<h3 id="install-globally">Install globally</h3>
|
||||
<p>If you prefer to install MkDocs once and reuse it across projects, then you can install it globally instead.</p>
|
||||
<p>MkDocs is available using package managers like <code>apt-get</code>, <code>homebrew</code> and <code>yum</code>.</p>
|
||||
<p>Or you can install like this:</p>
|
||||
<pre><code class="language-sh">$ python3 -m pip install mkdocs
|
||||
</code></pre>
|
||||
<p>If you get prompted for <code>sudo</code> use, then cancel and run again with <code>-U</code> flag for user-level install.</p>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="../setup-project/" class="btn btn-neutral float-right" title="Set up project">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
<a href="../tldr/" class="btn btn-neutral" title="TL;DR"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href="../tldr/" style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
<span><a href="../setup-project/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '../..';</script>
|
||||
<script src="../../js/theme_extra.js" defer></script>
|
||||
<script src="../../js/theme.js" defer></script>
|
||||
<script src="../../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,326 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/setup-project/">
|
||||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||||
<title>Set up project - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../../css/theme.css" />
|
||||
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "Set up project";
|
||||
var mkdocs_page_input_path = "tutorial/setup-project.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/setup-project/";
|
||||
</script>
|
||||
|
||||
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">Set up project</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#how-to-use-this-guide">How to use this guide</a>
|
||||
<ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#basic-structure">Basic structure</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#requirements-file">Requirements file</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#create-a-starter-site">Create a starter site</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#set-up-a-docs-site">Set up a docs site</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#sample-content">Sample content</a>
|
||||
<ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#ignore-file">Ignore file</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#navbar">Navbar</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#themes">Themes</a>
|
||||
<ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#builtin">Builtin</a>
|
||||
</li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#readthedocs-dropdown-theme">ReadTheDocs Dropdown theme</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#material-for-mkddocs-theme">Material for MkdDocs theme</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Tutorial »</li>
|
||||
|
||||
|
||||
|
||||
<li>Set up project</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/setup-project.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="set-up-project">Set up project</h1>
|
||||
<blockquote>
|
||||
<p>How to create a MkDocs site from scratch</p>
|
||||
</blockquote>
|
||||
<p>This is a summary of the tutorial on <a href="https://www.mkdocs.org/">mkdocs.org</a>.</p>
|
||||
<h2 id="how-to-use-this-guide">How to use this guide</h2>
|
||||
<p>Use one of the approaches below:</p>
|
||||
<ul>
|
||||
<li>Create a quickstart project with the <code>new</code> command covered in <a href="#create-a-starter-site">Create a starter site</a>.</li>
|
||||
<li>Follow the extended guide to create a <a href="#setup-a-docs-site">Set up up docs site</a> by hand.</li>
|
||||
</ul>
|
||||
<h3 id="basic-structure">Basic structure</h3>
|
||||
<p>This is the simplest MkDocs site you can make:</p>
|
||||
<ul>
|
||||
<li><code>docs/</code><ul>
|
||||
<li><code>index.md</code> - Homepage in the <code>docs</code> directory (by default).</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>mkdocs.yml</code><ul>
|
||||
<li>Config at the root - control appearance and navigation of your site.</li>
|
||||
<li>See this project's <a href="https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/docs/mkdocs.yml">docs/mkdocs.yml</a> file on GitHub.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Notes on fields for the config:</p>
|
||||
<ul>
|
||||
<li><code>site_name</code> - title of your site.</li>
|
||||
<li><code>site_description</code> - used as a description for SEO and you could use it somewhere in your template.</li>
|
||||
<li><code>site_url</code> - now a <em>required</em> 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.</li>
|
||||
<li><code>repo_url</code> - for <em>Edit on GitHub</em> button. See <a href="https://www.mkdocs.org/user-guide/configuration/#repo_url">docs</a>.</li>
|
||||
<li><code>edit_uri</code> - defaults to <code>edit/master/docs/</code>, which includes <code>docs</code> directory of markdown files inside your repo root. But, if the site's root is in an outer <code>docs</code> directory, then you need to <em>also</em> add that, so paths do not break. e.g. <code>edit/master/docs/docs</code>. See <a href="https://www.mkdocs.org/user-guide/configuration/#edit_uri">docs</a></li>
|
||||
</ul>
|
||||
<h3 id="requirements-file">Requirements file</h3>
|
||||
<p>A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure <code>pip install mkdocs</code> and <code>pip install THEME</code> lines are your instructions.</p>
|
||||
<p>If you want to add, then include <code>requirements.txt</code> at the root. If your project is already a Python project, you might prefer to add <code>mkdocs</code> in <code>requirements-dev.txt</code> or at <code>docs/requirements.txt</code> to keep it isolated.This file should have <code>mkdocs</code> in it and also any themes if needed.</p>
|
||||
<h3 id="create-a-starter-site">Create a starter site</h3>
|
||||
<p>Run this command to create a starter site. This make the steps below go quicker.</p>
|
||||
<pre><code class="language-sh">cd my-project
|
||||
mkdocs new PATH
|
||||
</code></pre>
|
||||
<p>The result will be same as the <a href="#basic-structure">Basic structure</a> defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's <a href="https://github.com/mkdocs/mkdocs/blob/master/mkdocs/commands/new.py">new.py</a> module.</p>
|
||||
<h3 id="set-up-a-docs-site">Set up a docs site</h3>
|
||||
<p><em>Tip: Optionally use the <code>new</code> command covered above to set up the config and index page first and then continue</em>.</p>
|
||||
<ol>
|
||||
<li>Create doc pages.<ol>
|
||||
<li>Create a <code>docs</code> directory.</li>
|
||||
<li>Create <code>index.md</code> as your homepage.</li>
|
||||
<li>Create other markdown pages (optional).<ul>
|
||||
<li>Use placeholder content if you want to move on and then come back to expand them.</li>
|
||||
<li>If you have any existing markdown docs, these will work too.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Set up config.<ol>
|
||||
<li>Create <code>mkdocs.yml</code> at the project root.</li>
|
||||
<li>Set up a navbar there.</li>
|
||||
<li>Choose a theme.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Create a favicon (optional).<ul>
|
||||
<li>It will be picked up at this path: <code>docs/img/favicon.ico</code>.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Add to your <code>.gitignore</code>.<ul>
|
||||
<li>Add build directory. This will prevent it from being versioned on <code>master</code> branch.</li>
|
||||
<li>Add virtual environment, if using one.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
<p>You project should now look this this:</p>
|
||||
<ul>
|
||||
<li><code>docs/</code><ul>
|
||||
<li><code>index.md</code></li>
|
||||
<li>More pages...</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>mkdocs.yml</code></li>
|
||||
<li><code>.gitignore</code></li>
|
||||
<li><code>venv</code></li>
|
||||
<li><code>requirements.txt</code> - optional</li>
|
||||
</ul>
|
||||
<h2 id="sample-content">Sample content</h2>
|
||||
<h3 id="ignore-file">Ignore file</h3>
|
||||
<p><code>.gitignore</code></p>
|
||||
<pre><code>site/
|
||||
|
||||
venv
|
||||
</code></pre>
|
||||
<h3 id="navbar">Navbar</h3>
|
||||
<p><code>mkdocs.yml</code></p>
|
||||
<pre><code class="language-yaml">nav:
|
||||
- Home: index.md
|
||||
- About: about.md
|
||||
</code></pre>
|
||||
<h3 id="themes">Themes</h3>
|
||||
<h4 id="builtin">Builtin</h4>
|
||||
<p>Use a builtin theme that comes with MkDocs.</p>
|
||||
<p>The default.</p>
|
||||
<pre><code class="language-yaml">theme: mkdocs
|
||||
</code></pre>
|
||||
<p>Using ReadTheDocs theme and alternative config syntax.</p>
|
||||
<pre><code class="language-yaml">theme:
|
||||
name: readthedocs
|
||||
</code></pre>
|
||||
<p>Find more <a href="https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes">supported themes</a>. If it doesn't immediately, you'll have to use <code>pip</code> to install it and add to a <code>requirements.txt</code> file.</p>
|
||||
<h4 id="readthedocs-dropdown-theme">ReadTheDocs Dropdown theme</h4>
|
||||
<p>See below using <a href="https://github.com/cjsheets/mkdocs-rtd-dropdown">mkdocs-rtd-dropdown</a>.</p>
|
||||
<p><code>requirements.txt</code>:</p>
|
||||
<pre><code>mkdocs-rtd-dropdown
|
||||
</code></pre>
|
||||
<p><code>mkdocs.yml</code>:</p>
|
||||
<pre><code class="language-yaml">theme:
|
||||
name: 'rtd-dropdown'
|
||||
</code></pre>
|
||||
<h3 id="material-for-mkddocs-theme">Material for MkdDocs theme</h3>
|
||||
<p>See the <a href="https://squidfunk.github.io/mkdocs-material/">MkDocs for Material</a> homepage. See the Set up page for config options.</p>
|
||||
<p><code>requirements.txt</code>:</p>
|
||||
<pre><code>mkdocs-material-extensions>=1.0
|
||||
</code></pre>
|
||||
<p><code>mkdocs.yml</code>:</p>
|
||||
<pre><code class="language-yaml">theme:
|
||||
name: 'material'
|
||||
</code></pre>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="../advanced/" class="btn btn-neutral float-right" title="Advanced">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
<a href="../installation/" class="btn btn-neutral" title="Installation"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href="../installation/" style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
<span><a href="../advanced/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '../..';</script>
|
||||
<script src="../../js/theme_extra.js" defer></script>
|
||||
<script src="../../js/theme.js" defer></script>
|
||||
<script src="../../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,214 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/tldr/">
|
||||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||||
<title>TL;DR - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../../css/theme.css" />
|
||||
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "TL;DR";
|
||||
var mkdocs_page_input_path = "tutorial/tldr.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/tldr/";
|
||||
</script>
|
||||
|
||||
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">TL;DR</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#local-setup">Local setup</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#deploy-to-remote-site">Deploy to remote site</a>
|
||||
<ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#run-deploy-command-locally">Run deploy command locally</a>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#run-continuous-integration">Run continuous integration</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../usage/">Usage</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Tutorial »</li>
|
||||
|
||||
|
||||
|
||||
<li>TL;DR</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/tldr.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="tldr">TL;DR</h1>
|
||||
<blockquote>
|
||||
<p>A simplified version of the tutorial.</p>
|
||||
</blockquote>
|
||||
<h2 id="local-setup">Local setup</h2>
|
||||
<ol>
|
||||
<li><a href="../installation/">Install</a><ul>
|
||||
<li><code>pip install mkdocs</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="../setup-project/">Set up project</a><ul>
|
||||
<li><code>mkdocs new .</code> or <a href="https://github.com/MichaelCurrin/mkdocs-quickstart/generate"><img alt="Use this template" src="https://img.shields.io/badge/Use_this_template-2ea44f&logo=github" /></a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="../usage/">Run</a><ul>
|
||||
<li><code>mkdocs serve</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>View on <a href="http://localhost:8000">localhost:8000</a></li>
|
||||
</ol>
|
||||
<h2 id="deploy-to-remote-site">Deploy to remote site</h2>
|
||||
<h3 id="run-deploy-command-locally">Run deploy command locally</h3>
|
||||
<ol>
|
||||
<li><a href="../deploy/">Deploy</a> to GitHub Pages<ul>
|
||||
<li><code>mkdocs gh-deploy</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>View published site on GitHub Pages at <code>https://USERNAME.github.io/REPO-NAME/</code></li>
|
||||
</ol>
|
||||
<h3 id="run-continuous-integration">Run continuous integration</h3>
|
||||
<p>For CI/CD deploy, use GitHub Actions with an action such as <a href="https://github.com/marketplace/actions/deploy-mkdocs">Deploy MkDocs</a>. Or use Netlify.</p>
|
||||
<p>This is not covered in this tutorial.</p>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="../installation/" class="btn btn-neutral float-right" title="Installation">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
<a href="../../about-mkdocs/" class="btn btn-neutral" title="About MkDocs"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href="../../about-mkdocs/" style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
<span><a href="../installation/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '../..';</script>
|
||||
<script src="../../js/theme_extra.js" defer></script>
|
||||
<script src="../../js/theme.js" defer></script>
|
||||
<script src="../../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,209 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
||||
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
|
||||
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/usage/">
|
||||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||||
<title>Usage - MkDocs Quickstart</title>
|
||||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
||||
|
||||
<link rel="stylesheet" href="../../css/theme.css" />
|
||||
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
||||
|
||||
<script>
|
||||
// Current page data
|
||||
var mkdocs_page_name = "Usage";
|
||||
var mkdocs_page_input_path = "tutorial/usage.md";
|
||||
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/usage/";
|
||||
</script>
|
||||
|
||||
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
||||
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
||||
<script>hljs.initHighlightingOnLoad();</script>
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav" role="document">
|
||||
|
||||
<div class="wy-grid-for-nav">
|
||||
|
||||
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search">
|
||||
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
||||
<div role="search">
|
||||
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../tldr/">TL;DR</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../setup-project/">Set up project</a>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../advanced/">Advanced</a>
|
||||
</li>
|
||||
<li class="toctree-l1 current"><a class="reference internal current" href="./">Usage</a>
|
||||
<ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="#cli-help">CLI help</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#serve-docs">Serve docs</a>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="#build-docs">Build docs</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../deploy/">Deploy</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||||
|
||||
|
||||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../..">MkDocs Quickstart</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../..">Docs</a> »</li>
|
||||
|
||||
|
||||
|
||||
<li>Tutorial »</li>
|
||||
|
||||
|
||||
|
||||
<li>Usage</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/usage.md"
|
||||
class="icon icon-github"> Edit on GitHub</a>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
</div>
|
||||
|
||||
<div role="main">
|
||||
<div class="section">
|
||||
|
||||
<h1 id="usage">Usage</h1>
|
||||
<blockquote>
|
||||
<p>Build and preview a site locally</p>
|
||||
</blockquote>
|
||||
<p>Make sure to run all commands from the <code>docs</code> directory, as that is where <code>Makefile</code> is.</p>
|
||||
<pre><code class="language-sh">$ cd docs
|
||||
</code></pre>
|
||||
<h2 id="cli-help">CLI help</h2>
|
||||
<pre><code class="language-sh">$ make help
|
||||
</code></pre>
|
||||
<pre><code>default: install
|
||||
all: install build
|
||||
h help:
|
||||
install:
|
||||
upgrade:
|
||||
s serve:
|
||||
b build:
|
||||
d deploy:
|
||||
</code></pre>
|
||||
<h2 id="serve-docs">Serve docs</h2>
|
||||
<p>This will build the docs in memory (not to disk) and serve an auto-reloading server.</p>
|
||||
<pre><code class="language-sh">$ make serve
|
||||
</code></pre>
|
||||
<p>Then open in your browser:</p>
|
||||
<ul>
|
||||
<li><a href="http://localhost:8000">localhost:8000</a></li>
|
||||
</ul>
|
||||
<h2 id="build-docs">Build docs</h2>
|
||||
<p>Build docs site to <code>site</code> directory. This is useful for a CI flow.</p>
|
||||
<pre><code class="language-sh">$ make build
|
||||
</code></pre>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer>
|
||||
|
||||
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
||||
|
||||
<a href="../deploy/" class="btn btn-neutral float-right" title="Deploy">Next <span class="icon icon-circle-arrow-right"></span></a>
|
||||
|
||||
|
||||
<a href="../advanced/" class="btn btn-neutral" title="Advanced"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<!-- Copyright etc -->
|
||||
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
</footer>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
|
||||
<span>
|
||||
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
||||
</span>
|
||||
|
||||
|
||||
<span><a href="../advanced/" style="color: #fcfcfc">« Previous</a></span>
|
||||
|
||||
|
||||
<span><a href="../deploy/" style="color: #fcfcfc">Next »</a></span>
|
||||
|
||||
</span>
|
||||
</div>
|
||||
<script>var base_url = '../..';</script>
|
||||
<script src="../../js/theme_extra.js" defer></script>
|
||||
<script src="../../js/theme.js" defer></script>
|
||||
<script src="../../search/main.js" defer></script>
|
||||
<script defer>
|
||||
window.onload = function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
};
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user