iarv/mkdocs-quickstart
1
0
Fork 0
mirror of https://github.com/MichaelCurrin/mkdocs-quickstart.git synced 2026-03-28 17:42:47 +01:00
Code Issues Packages Projects Releases Wiki Activity

Deployed e568b53 with MkDocs version: 1.2.2

Browse Source
This commit is contained in:
2021-07-28 11:07:01 +00:00
commit 22207dc159
54 changed files with 8778 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
tutorial/advanced/index.html Normal file
View File

@@ -0,0 +1,221 @@
<!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> &raquo;</li>
<li>Tutorial &raquo;</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">&lt;script src=&quot;https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js&quot;&gt;&lt;/script&gt;
</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">&laquo; Previous</a></span>
<span><a href="../usage/" style="color: #fcfcfc">Next &raquo;</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>

220
tutorial/deploy/index.html Normal file
View File

@@ -0,0 +1,220 @@
<!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> &raquo;</li>
<li>Tutorial &raquo;</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">&laquo; 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>

231
tutorial/installation/index.html Normal file
View File

@@ -0,0 +1,231 @@
<!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> &raquo;</li>
<li>Tutorial &raquo;</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&amp;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">&laquo; Previous</a></span>
<span><a href="../setup-project/" style="color: #fcfcfc">Next &raquo;</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>

326
tutorial/setup-project/index.html Normal file
View File

@@ -0,0 +1,326 @@
<!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> &raquo;</li>
<li>Tutorial &raquo;</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&gt;=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">&laquo; Previous</a></span>
<span><a href="../advanced/" style="color: #fcfcfc">Next &raquo;</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>

214
tutorial/tldr/index.html Normal file
View File

@@ -0,0 +1,214 @@
<!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> &raquo;</li>
<li>Tutorial &raquo;</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&amp;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">&laquo; Previous</a></span>
<span><a href="../installation/" style="color: #fcfcfc">Next &raquo;</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>

209
tutorial/usage/index.html Normal file
View File

@@ -0,0 +1,209 @@
<!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> &raquo;</li>
<li>Tutorial &raquo;</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">&laquo; Previous</a></span>
<span><a href="../deploy/" style="color: #fcfcfc">Next &raquo;</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>