mirror of
https://github.com/mkdocs/mkdocs.git
synced 2026-03-27 18:08:31 +07:00
413 lines
18 KiB
HTML
413 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<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="Project documentation with Markdown.">
|
|
<meta name="author" content="Tom Christie & Dougal Matthews">
|
|
<link rel="canonical" href="http://www.mkdocs.org/">
|
|
<link rel="shortcut icon" href="./img/favicon.ico">
|
|
|
|
<title>MkDocs</title>
|
|
|
|
<link href="./css/bootstrap-custom.min.css" rel="stylesheet">
|
|
<link href="./css/font-awesome-4.5.0.css" rel="stylesheet">
|
|
<link href="./css/base.css" rel="stylesheet">
|
|
<link rel="stylesheet" href="./css/highlight.css">
|
|
<link href="./css/extra.css" rel="stylesheet">
|
|
|
|
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
|
|
<!--[if lt IE 9]>
|
|
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
|
|
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
|
|
<![endif]-->
|
|
|
|
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-27795084-5', 'mkdocs.org');
|
|
ga('send', 'pageview');
|
|
</script>
|
|
|
|
</head>
|
|
|
|
<body class="homepage">
|
|
|
|
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
|
|
<div class="container">
|
|
|
|
<!-- Collapsed navigation -->
|
|
<div class="navbar-header">
|
|
|
|
<!-- Expander button -->
|
|
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
|
|
<span class="sr-only">Toggle navigation</span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</button>
|
|
|
|
|
|
<!-- Main title -->
|
|
<a class="navbar-brand" href=".">MkDocs</a>
|
|
</div>
|
|
|
|
<!-- Expanded navigation -->
|
|
<div class="navbar-collapse collapse">
|
|
|
|
<!-- Main navigation -->
|
|
<ul class="nav navbar-nav">
|
|
|
|
|
|
<li class="active">
|
|
<a href=".">Home</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">User Guide <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
|
|
<li >
|
|
<a href="user-guide/writing-your-docs/">Writing Your Docs</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="user-guide/styling-your-docs/">Styling Your Docs</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="user-guide/configuration/">Configuration</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="user-guide/deploying-your-docs/">Deploying Your Docs</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="user-guide/custom-themes/">Custom Themes</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">About <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
|
|
<li >
|
|
<a href="about/release-notes/">Release Notes</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="about/contributing/">Contributing</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="about/license/">License</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<ul class="nav navbar-nav navbar-right">
|
|
<li>
|
|
<a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
|
|
<i class="fa fa-search"></i> Search
|
|
</a>
|
|
</li>
|
|
|
|
<li class="disabled">
|
|
<a rel="next" >
|
|
<i class="fa fa-arrow-left"></i> Previous
|
|
</a>
|
|
</li>
|
|
<li >
|
|
<a rel="prev" href="user-guide/writing-your-docs/">
|
|
Next <i class="fa fa-arrow-right"></i>
|
|
</a>
|
|
</li>
|
|
|
|
|
|
<li>
|
|
<a href="https://github.com/mkdocs/mkdocs/">
|
|
|
|
<i class="fa fa-github"></i>
|
|
|
|
GitHub
|
|
</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="container">
|
|
|
|
<div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
|
|
<ul class="nav bs-sidenav">
|
|
|
|
<li class="main active"><a href="#mkdocs">MkDocs</a></li>
|
|
|
|
<li><a href="#overview">Overview</a></li>
|
|
|
|
<li><a href="#installation">Installation</a></li>
|
|
|
|
<li><a href="#getting-started">Getting started</a></li>
|
|
|
|
<li><a href="#adding-pages">Adding pages</a></li>
|
|
|
|
<li><a href="#theming-our-documentation">Theming our documentation</a></li>
|
|
|
|
<li><a href="#building-the-site">Building the site</a></li>
|
|
|
|
<li><a href="#other-commands-and-options">Other Commands and Options</a></li>
|
|
|
|
<li><a href="#deploying">Deploying</a></li>
|
|
|
|
<li><a href="#getting-help">Getting help</a></li>
|
|
|
|
|
|
</ul>
|
|
</div></div>
|
|
<div class="col-md-9" role="main">
|
|
|
|
<h1 id="mkdocs">MkDocs<a class="headerlink" href="#mkdocs" title="Permanent link"></a></h1>
|
|
<p>Project documentation with Markdown.</p>
|
|
<hr />
|
|
<h2 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link"></a></h2>
|
|
<p>MkDocs is a <strong>fast</strong>, <strong>simple</strong> and <strong>downright gorgeous</strong> static site
|
|
generator that's geared towards building project documentation. Documentation
|
|
source files are written in Markdown, and configured with a single YAML
|
|
configuration file.</p>
|
|
<h3 id="host-anywhere">Host anywhere<a class="headerlink" href="#host-anywhere" title="Permanent link"></a></h3>
|
|
<p>Builds completely static HTML sites that you can host on GitHub pages, Amazon
|
|
S3, or anywhere else you choose.</p>
|
|
<h3 id="great-themes-available">Great themes available<a class="headerlink" href="#great-themes-available" title="Permanent link"></a></h3>
|
|
<p>There's a stack of good looking themes included by default. Choose from
|
|
bootstrap, readthedocs, or any of the 12 bootswatch themes.</p>
|
|
<h3 id="preview-your-site-as-you-work">Preview your site as you work<a class="headerlink" href="#preview-your-site-as-you-work" title="Permanent link"></a></h3>
|
|
<p>The built-in devserver allows you to preview your documentation as you're
|
|
writing it. It will even auto-reload whenever you save any changes, so all you
|
|
need to do to see your latest edits is refresh your browser.</p>
|
|
<h3 id="easy-to-customize">Easy to customize<a class="headerlink" href="#easy-to-customize" title="Permanent link"></a></h3>
|
|
<p>Get your project documentation looking just the way you want it by customizing
|
|
the theme.</p>
|
|
<hr />
|
|
<h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link"></a></h2>
|
|
<p>In order to install MkDocs you'll need <a href="https://www.python.org/">Python</a> installed on your system, as
|
|
well as the Python package manager, <a href="http://pip.readthedocs.org/en/latest/installing.html">pip</a>. You can check if you have these
|
|
already installed like so:</p>
|
|
<pre><code class="bash">$ python --version
|
|
Python 2.7.2
|
|
$ pip --version
|
|
pip 1.5.2
|
|
</code></pre>
|
|
|
|
<p>MkDocs supports Python 2.6, 2.7, 3.3 and 3.4.</p>
|
|
<p>On Windows we recommend that you install Python and pip with <a href="https://chocolatey.org/">Chocolatey</a>.</p>
|
|
<p>Install the <code>mkdocs</code> package using pip:</p>
|
|
<pre><code class="bash">pip install mkdocs
|
|
</code></pre>
|
|
|
|
<p>You should now have the <code>mkdocs</code> command installed on your system. Run <code>mkdocs
|
|
--version</code> to check that everything worked okay.</p>
|
|
<pre><code class="bash">$ mkdocs --version
|
|
mkdocs, version 0.14.0
|
|
</code></pre>
|
|
|
|
<hr />
|
|
<h2 id="getting-started">Getting started<a class="headerlink" href="#getting-started" title="Permanent link"></a></h2>
|
|
<p>Getting started is super easy.</p>
|
|
<pre><code class="bash">mkdocs new my-project
|
|
cd my-project
|
|
</code></pre>
|
|
|
|
<p>Let's take a moment to review the initial project that's been created for us.</p>
|
|
<p><img alt="The initial MkDocs layout" src="./img/initial-layout.png" /></p>
|
|
<p>There's a single configuration file named <code>mkdocs.yml</code>, and a folder named
|
|
<code>docs</code> that will contain our documentation source files. Right now the <code>docs</code>
|
|
folder just contains a single documentation page, named <code>index.md</code>.</p>
|
|
<p>MkDocs comes with a built-in webserver that lets you preview your documentation
|
|
as you work on it. We start the webserver by making sure we're in the same
|
|
directory as the <code>mkdocs.yml</code> config file, and then running the <code>mkdocs serve</code>
|
|
command:</p>
|
|
<pre><code class="bash">$ mkdocs serve
|
|
Running at: http://127.0.0.1:8000/
|
|
</code></pre>
|
|
|
|
<p>Open up <a href="http://127.0.0.1:8000/">http://127.0.0.1:8000/</a> in your browser, and
|
|
you'll see the index page being displayed:</p>
|
|
<p><img alt="The MkDocs live server" src="./img/screenshot.png" /></p>
|
|
<p>The webserver also supports auto-reloading, and will rebuild your documentation
|
|
whenever anything in the configuration file, documentation directory or theme
|
|
directory changes.</p>
|
|
<p>Go ahead and edit the <code>docs/index.md</code> file now and save the file. Then simply
|
|
hit reload in the browser and you'll see your updated documentation.</p>
|
|
<p>Now's also a good time to edit the configuration file, <code>mkdocs.yml</code>. Change the
|
|
<code>site_name</code> setting to something else and save the file.</p>
|
|
<p><img alt="Editing the config file" src="./img/initial-config.png" /></p>
|
|
<p>Once you hit reload in the browser you'll see your new site name take effect.</p>
|
|
<p><img alt="The site_name setting" src="./img/site-name.png" /></p>
|
|
<h2 id="adding-pages">Adding pages<a class="headerlink" href="#adding-pages" title="Permanent link"></a></h2>
|
|
<p>Go ahead and edit the <code>docs/index.md</code> document, and change the initial heading to
|
|
<code>MkLorum</code>, then reload the site in your browser, and you should see the change
|
|
take effect immediately.</p>
|
|
<p>Let's also add a second page to our documentation:</p>
|
|
<pre><code class="bash">curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
|
|
</code></pre>
|
|
|
|
<p>We'd like our documentation site to include some navigation headers, so we'll
|
|
edit the configuration file and add some information about the order and title
|
|
to use for out headers:</p>
|
|
<pre><code class="no-highlight">site_name: MkLorum
|
|
pages:
|
|
- Home: index.md
|
|
- About: about.md
|
|
</code></pre>
|
|
|
|
<p>Refresh the browser and you'll now see a navigation bar with <code>Home</code> and <code>About</code>
|
|
headers.</p>
|
|
<h2 id="theming-our-documentation">Theming our documentation<a class="headerlink" href="#theming-our-documentation" title="Permanent link"></a></h2>
|
|
<p>While we're here can also change the configuration file to alter how the
|
|
documentation is displayed. Let's go ahead and change the theme. Edit the
|
|
<code>mkdocs.yml</code> file to the following:</p>
|
|
<pre><code class="no-highlight">site_name: MkLorum
|
|
pages:
|
|
- Home: index.md
|
|
- About: about.md
|
|
theme: readthedocs
|
|
</code></pre>
|
|
|
|
<p>Refresh the browser again, and you'll now see the ReadTheDocs theme being used.</p>
|
|
<p><img alt="Screenshot" src="./img/readthedocs.png" /></p>
|
|
<h2 id="building-the-site">Building the site<a class="headerlink" href="#building-the-site" title="Permanent link"></a></h2>
|
|
<p>That's looking good. We're ready to deploy the first pass of our <code>MkLorum</code>
|
|
documentation now. Let's build the documentation.</p>
|
|
<pre><code class="bash">mkdocs build
|
|
</code></pre>
|
|
|
|
<p>This will create a new directory, named <code>site</code>. Let's take a look inside the
|
|
directory:</p>
|
|
<pre><code class="bash">ls site
|
|
about css fonts img index.html js
|
|
</code></pre>
|
|
|
|
<p>Notice that our source documentation has been output as two HTML files named
|
|
<code>index.html</code> and <code>about/index.html</code>. We also have various other media that's
|
|
been copied into the <code>site</code> directory as part of the documentation theme.</p>
|
|
<p>If you're using source code control such as <code>git</code> you probably don't want to
|
|
check your documentation builds into the repository. Add a line containing
|
|
<code>site/</code> to your <code>.gitignore</code> file.</p>
|
|
<pre><code class="bash">echo "site/" >> .gitignore
|
|
</code></pre>
|
|
|
|
<p>If you're using another source code control you'll want to check it's
|
|
documentation on how to ignore specific directories.</p>
|
|
<p>After some time, files may be removed from the documentation but they will still
|
|
reside in the <code>site</code> directory. To remove those stale files, just run mkdocs
|
|
with the <code>--clean</code> switch.</p>
|
|
<pre><code class="bash">mkdocs build --clean
|
|
</code></pre>
|
|
|
|
<h2 id="other-commands-and-options">Other Commands and Options<a class="headerlink" href="#other-commands-and-options" title="Permanent link"></a></h2>
|
|
<p>There are various other commands and options available. For a complete list of
|
|
commands, use the <code>--help</code> flag:</p>
|
|
<pre><code class="bash">mkdocs --help
|
|
</code></pre>
|
|
|
|
<p>To view a list of options available on a given command, use the <code>--help</code> flag
|
|
with that command. For example, to get a list of all options available for the
|
|
<code>build</code> command run the following:</p>
|
|
<pre><code class="bash">mkdocs build --help
|
|
</code></pre>
|
|
|
|
<h2 id="deploying">Deploying<a class="headerlink" href="#deploying" title="Permanent link"></a></h2>
|
|
<p>The documentation site that we've just built only uses static files so you'll be
|
|
able to host it from pretty much anywhere. <a href="https://help.github.com/articles/creating-project-pages-manually">GitHub project pages</a> and <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html">Amazon
|
|
S3</a> are good hosting options. Upload the contents of the entire <code>site</code> directory
|
|
to wherever you're hosting your website from and you're done. For specific
|
|
instructions for a number of common hosts, see the <a href="user-guide/deploying-your-docs/">Deploying your Docs</a> page.</p>
|
|
<h2 id="getting-help">Getting help<a class="headerlink" href="#getting-help" title="Permanent link"></a></h2>
|
|
<p>To get help with MkDocs, please use the <a href="https://groups.google.com/forum/#!forum/mkdocs">discussion group</a>, <a href="https://github.com/mkdocs/mkdocs/issues">GitHub issues</a> or
|
|
the MkDocs IRC channel <code>#mkdocs</code> on freenode.</p></div>
|
|
|
|
</div>
|
|
|
|
<footer class="col-md-12">
|
|
<hr>
|
|
|
|
<p>Copyright © 2014 <a href="https://twitter.com/_tomchristie">Tom Christie</a>, <a href="http://www.dougalmatthews.com/">Dougal Matthews</a>.</p>
|
|
|
|
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p>
|
|
</footer>
|
|
|
|
<script src="./js/jquery-1.10.2.min.js"></script>
|
|
<script src="./js/bootstrap-3.0.3.min.js"></script>
|
|
<script src="./js/highlight.pack.js"></script>
|
|
<script>var base_url = '.';</script>
|
|
<script data-main="./mkdocs/js/search.js" src="./mkdocs/js/require.js"></script>
|
|
<script src="./js/base.js"></script>
|
|
|
|
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true">
|
|
<div class="modal-dialog">
|
|
<div class="modal-content">
|
|
<div class="modal-header">
|
|
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button>
|
|
<h4 class="modal-title" id="exampleModalLabel">Search</h4>
|
|
</div>
|
|
<div class="modal-body">
|
|
<p>
|
|
From here you can search these documents. Enter
|
|
your search terms below.
|
|
</p>
|
|
<form role="form">
|
|
<div class="form-group">
|
|
<input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query">
|
|
</div>
|
|
</form>
|
|
<div id="mkdocs-search-results"></div>
|
|
</div>
|
|
<div class="modal-footer">
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
<!--
|
|
MkDocs version : 0.15.1
|
|
Build Date UTC : 2016-01-30 19:09:24.880382
|
|
-->
|