mirror of
https://github.com/MichaelCurrin/mkdocs-quickstart.git
synced 2026-03-28 17:42:47 +01:00
327 lines
13 KiB
HTML
327 lines
13 KiB
HTML
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
|
|
<link rel="canonical" href="https://michaelcurrin.github.io/mkdocs-quickstart/tutorial/setup-project/">
|
|
<link rel="shortcut icon" href="../../img/favicon.ico">
|
|
<title>Set up project - MkDocs Quickstart</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
|
|
|
|
<link rel="stylesheet" href="../../css/theme.css" />
|
|
<link rel="stylesheet" href="../../css/theme_extra.css" />
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
|
|
|
|
<script>
|
|
// Current page data
|
|
var mkdocs_page_name = "Set up project";
|
|
var mkdocs_page_input_path = "tutorial/setup-project.md";
|
|
var mkdocs_page_url = "/mkdocs-quickstart/tutorial/setup-project/";
|
|
</script>
|
|
|
|
<script src="../../js/jquery-2.1.1.min.js" defer></script>
|
|
<script src="../../js/modernizr-2.8.3.min.js" defer></script>
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
|
|
<script>hljs.initHighlightingOnLoad();</script>
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
|
<div class="wy-side-scroll">
|
|
<div class="wy-side-nav-search">
|
|
<a href="../.." class="icon icon-home"> MkDocs Quickstart</a>
|
|
<div role="search">
|
|
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
|
</form>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="../..">Home</a>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="../../about-mkdocs/">About MkDocs</a>
|
|
</li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Tutorial</span></p>
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="../tldr/">TL;DR</a>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a>
|
|
</li>
|
|
<li class="toctree-l1 current"><a class="reference internal current" href="./">Set up project</a>
|
|
<ul class="current">
|
|
<li class="toctree-l2"><a class="reference internal" href="#how-to-use-this-guide">How to use this guide</a>
|
|
<ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#basic-structure">Basic structure</a>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#requirements-file">Requirements file</a>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#create-a-starter-site">Create a starter site</a>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#set-up-a-docs-site">Set up a docs site</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#sample-content">Sample content</a>
|
|
<ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#ignore-file">Ignore file</a>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#navbar">Navbar</a>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#themes">Themes</a>
|
|
<ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="#builtin">Builtin</a>
|
|
</li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#readthedocs-dropdown-theme">ReadTheDocs Dropdown theme</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#material-for-mkddocs-theme">Material for MkdDocs theme</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../advanced/">Advanced</a>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/">Usage</a>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../deploy/">Deploy</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="../..">MkDocs Quickstart</a>
|
|
</nav>
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="../..">Docs</a> »</li>
|
|
|
|
|
|
|
|
<li>Tutorial »</li>
|
|
|
|
|
|
|
|
<li>Set up project</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/edit/master/docs/docs/tutorial/setup-project.md"
|
|
class="icon icon-github"> Edit on GitHub</a>
|
|
|
|
</li>
|
|
</ul>
|
|
|
|
<hr/>
|
|
</div>
|
|
|
|
<div role="main">
|
|
<div class="section">
|
|
|
|
<h1 id="set-up-project">Set up project</h1>
|
|
<blockquote>
|
|
<p>How to create a MkDocs site from scratch</p>
|
|
</blockquote>
|
|
<p>This is a summary of the tutorial on <a href="https://www.mkdocs.org/">mkdocs.org</a>.</p>
|
|
<h2 id="how-to-use-this-guide">How to use this guide</h2>
|
|
<p>Use one of the approaches below:</p>
|
|
<ul>
|
|
<li>Create a quickstart project with the <code>new</code> command covered in <a href="#create-a-starter-site">Create a starter site</a>.</li>
|
|
<li>Follow the extended guide to create a <a href="#setup-a-docs-site">Set up up docs site</a> by hand.</li>
|
|
</ul>
|
|
<h3 id="basic-structure">Basic structure</h3>
|
|
<p>This is the simplest MkDocs site you can make:</p>
|
|
<ul>
|
|
<li><code>docs/</code><ul>
|
|
<li><code>index.md</code> - Homepage in the <code>docs</code> directory (by default).</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>mkdocs.yml</code><ul>
|
|
<li>Config at the root - control appearance and navigation of your site.</li>
|
|
<li>See this project's <a href="https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/docs/mkdocs.yml">docs/mkdocs.yml</a> file on GitHub.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Notes on fields for the config:</p>
|
|
<ul>
|
|
<li><code>site_name</code> - title of your site.</li>
|
|
<li><code>site_description</code> - used as a description for SEO and you could use it somewhere in your template.</li>
|
|
<li><code>site_url</code> - now a <em>required</em> field when running a deploy. Include the subpath on the domain. If your site is not ready to be hosted, set this field to an empty string.</li>
|
|
<li><code>repo_url</code> - for <em>Edit on GitHub</em> button. See <a href="https://www.mkdocs.org/user-guide/configuration/#repo_url">docs</a>.</li>
|
|
<li><code>edit_uri</code> - defaults to <code>edit/master/docs/</code>, which includes <code>docs</code> directory of markdown files inside your repo root. But, if the site's root is in an outer <code>docs</code> directory, then you need to <em>also</em> add that, so paths do not break. e.g. <code>edit/master/docs/docs</code>. See <a href="https://www.mkdocs.org/user-guide/configuration/#edit_uri">docs</a></li>
|
|
</ul>
|
|
<h3 id="requirements-file">Requirements file</h3>
|
|
<p>A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure <code>pip install mkdocs</code> and <code>pip install THEME</code> lines are your instructions.</p>
|
|
<p>If you want to add, then include <code>requirements.txt</code> at the root. If your project is already a Python project, you might prefer to add <code>mkdocs</code> in <code>requirements-dev.txt</code> or at <code>docs/requirements.txt</code> to keep it isolated.This file should have <code>mkdocs</code> in it and also any themes if needed.</p>
|
|
<h3 id="create-a-starter-site">Create a starter site</h3>
|
|
<p>Run this command to create a starter site. This make the steps below go quicker.</p>
|
|
<pre><code class="language-sh">cd my-project
|
|
mkdocs new PATH
|
|
</code></pre>
|
|
<p>The result will be same as the <a href="#basic-structure">Basic structure</a> defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's <a href="https://github.com/mkdocs/mkdocs/blob/master/mkdocs/commands/new.py">new.py</a> module.</p>
|
|
<h3 id="set-up-a-docs-site">Set up a docs site</h3>
|
|
<p><em>Tip: Optionally use the <code>new</code> command covered above to set up the config and index page first and then continue</em>.</p>
|
|
<ol>
|
|
<li>Create doc pages.<ol>
|
|
<li>Create a <code>docs</code> directory.</li>
|
|
<li>Create <code>index.md</code> as your homepage.</li>
|
|
<li>Create other markdown pages (optional).<ul>
|
|
<li>Use placeholder content if you want to move on and then come back to expand them.</li>
|
|
<li>If you have any existing markdown docs, these will work too.</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>Set up config.<ol>
|
|
<li>Create <code>mkdocs.yml</code> at the project root.</li>
|
|
<li>Set up a navbar there.</li>
|
|
<li>Choose a theme.</li>
|
|
</ol>
|
|
</li>
|
|
<li>Create a favicon (optional).<ul>
|
|
<li>It will be picked up at this path: <code>docs/img/favicon.ico</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Add to your <code>.gitignore</code>.<ul>
|
|
<li>Add build directory. This will prevent it from being versioned on <code>master</code> branch.</li>
|
|
<li>Add virtual environment, if using one.</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
<p>You project should now look this this:</p>
|
|
<ul>
|
|
<li><code>docs/</code><ul>
|
|
<li><code>index.md</code></li>
|
|
<li>More pages...</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>mkdocs.yml</code></li>
|
|
<li><code>.gitignore</code></li>
|
|
<li><code>venv</code></li>
|
|
<li><code>requirements.txt</code> - optional</li>
|
|
</ul>
|
|
<h2 id="sample-content">Sample content</h2>
|
|
<h3 id="ignore-file">Ignore file</h3>
|
|
<p><code>.gitignore</code></p>
|
|
<pre><code>site/
|
|
|
|
venv
|
|
</code></pre>
|
|
<h3 id="navbar">Navbar</h3>
|
|
<p><code>mkdocs.yml</code></p>
|
|
<pre><code class="language-yaml">nav:
|
|
- Home: index.md
|
|
- About: about.md
|
|
</code></pre>
|
|
<h3 id="themes">Themes</h3>
|
|
<h4 id="builtin">Builtin</h4>
|
|
<p>Use a builtin theme that comes with MkDocs.</p>
|
|
<p>The default.</p>
|
|
<pre><code class="language-yaml">theme: mkdocs
|
|
</code></pre>
|
|
<p>Using ReadTheDocs theme and alternative config syntax.</p>
|
|
<pre><code class="language-yaml">theme:
|
|
name: readthedocs
|
|
</code></pre>
|
|
<p>Find more <a href="https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes">supported themes</a>. If it doesn't immediately, you'll have to use <code>pip</code> to install it and add to a <code>requirements.txt</code> file.</p>
|
|
<h4 id="readthedocs-dropdown-theme">ReadTheDocs Dropdown theme</h4>
|
|
<p>See below using <a href="https://github.com/cjsheets/mkdocs-rtd-dropdown">mkdocs-rtd-dropdown</a>.</p>
|
|
<p><code>requirements.txt</code>:</p>
|
|
<pre><code>mkdocs-rtd-dropdown
|
|
</code></pre>
|
|
<p><code>mkdocs.yml</code>:</p>
|
|
<pre><code class="language-yaml">theme:
|
|
name: 'rtd-dropdown'
|
|
</code></pre>
|
|
<h3 id="material-for-mkddocs-theme">Material for MkdDocs theme</h3>
|
|
<p>See the <a href="https://squidfunk.github.io/mkdocs-material/">MkDocs for Material</a> homepage. See the Set up page for config options.</p>
|
|
<p><code>requirements.txt</code>:</p>
|
|
<pre><code>mkdocs-material-extensions>=1.0
|
|
</code></pre>
|
|
<p><code>mkdocs.yml</code>:</p>
|
|
<pre><code class="language-yaml">theme:
|
|
name: 'material'
|
|
</code></pre>
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="../advanced/" class="btn btn-neutral float-right" title="Advanced">Next <span class="icon icon-circle-arrow-right"></span></a>
|
|
|
|
|
|
<a href="../installation/" class="btn btn-neutral" title="Installation"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<!-- Copyright etc -->
|
|
|
|
</div>
|
|
|
|
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
<div class="rst-versions" role="note" aria-label="versions">
|
|
<span class="rst-current-version" data-toggle="rst-current-version">
|
|
|
|
<span>
|
|
<a href="https://github.com/MichaelCurrin/mkdocs-quickstart/" class="fa fa-github" style="color: #fcfcfc"> GitHub</a>
|
|
</span>
|
|
|
|
|
|
<span><a href="../installation/" style="color: #fcfcfc">« Previous</a></span>
|
|
|
|
|
|
<span><a href="../advanced/" style="color: #fcfcfc">Next »</a></span>
|
|
|
|
</span>
|
|
</div>
|
|
<script>var base_url = '../..';</script>
|
|
<script src="../../js/theme_extra.js" defer></script>
|
|
<script src="../../js/theme.js" defer></script>
|
|
<script src="../../search/main.js" defer></script>
|
|
<script defer>
|
|
window.onload = function () {
|
|
SphinxRtdTheme.Navigation.enable(true);
|
|
};
|
|
</script>
|
|
|
|
</body>
|
|
</html>
|