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

0
.nojekyll Normal file
View File

146
404.html Normal file
View File

@@ -0,0 +1,146 @@
<!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> &raquo;</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>

212
about-mkdocs/index.html Normal file
View File

@@ -0,0 +1,212 @@
<!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> &raquo;</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">&laquo; Previous</a></span>
<span><a href="../tutorial/tldr/" 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>

14
css/theme.css Normal file
View File

File diff suppressed because one or more lines are too long

191
css/theme_extra.css Normal file
View File

@@ -0,0 +1,191 @@
/*
* 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;
}

BIN
fonts/Lato/lato-bold.eot Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bold.ttf Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bold.woff Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bold.woff2 Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bolditalic.eot Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bolditalic.ttf Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bolditalic.woff Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-bolditalic.woff2 Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-italic.eot Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-italic.ttf Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-italic.woff Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-italic.woff2 Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-regular.eot Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-regular.ttf Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-regular.woff Normal file
View File

Binary file not shown.

BIN
fonts/Lato/lato-regular.woff2 Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-bold.eot Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-bold.ttf Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-bold.woff Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-bold.woff2 Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-regular.eot Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-regular.ttf Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-regular.woff Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab-v7-regular.woff2 Normal file
View File

Binary file not shown.

BIN
fonts/RobotoSlab/roboto-slab.eot Normal file
View File

Binary file not shown.

BIN
fonts/fontawesome-webfont.eot Normal file
View File

Binary file not shown.

2671
fonts/fontawesome-webfont.svg Normal file
View File

File diff suppressed because it is too large Load Diff
Side by Side

After

Width:  |  Height:  |  Size: 434 KiB

BIN
fonts/fontawesome-webfont.ttf Normal file
View File

Binary file not shown.

BIN
fonts/fontawesome-webfont.woff Normal file
View File

Binary file not shown.

BIN
fonts/fontawesome-webfont.woff2 Normal file
View File

Binary file not shown.

BIN
img/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

200
index.html Normal file
View File

@@ -0,0 +1,200 @@
<!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> &raquo;</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 &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>
<!--
MkDocs version : 1.2.2
Build Date UTC : 2021-07-28 11:07:01.106767+00:00
-->

4
js/jquery-2.1.1.min.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

1
js/modernizr-2.8.3.min.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

3
js/theme.js Normal file
View File

@@ -0,0 +1,3 @@
/* 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"]);

8
js/theme_extra.js Normal file
View File

@@ -0,0 +1,8 @@
/*
* 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');

153
search.html Normal file
View File

@@ -0,0 +1,153 @@
<!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> &raquo;</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
search/lunr.js Normal file
View File

File diff suppressed because it is too large Load Diff

102
search/main.js Normal file
View File

@@ -0,0 +1,102 @@
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;
}

1
search/search_index.json Normal file
View File

File diff suppressed because one or more lines are too long

133
search/worker.js Normal file
View File

@@ -0,0 +1,133 @@
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
sitemap.xml Normal file
View File

@@ -0,0 +1,43 @@
<?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>

BIN
sitemap.xml.gz Normal file
View File

Binary file not shown.

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>