diff --git a/docs/index.md b/docs/index.md index ce368876..653dd85b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ Project documentation with Markdown. ## Overview -MkDocs is a **fast**, **simple** and **downright gorgeous** 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. +MkDocs is a **fast**, **simple** and **downright gorgeous** 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. #### Host anywhere. @@ -14,11 +14,11 @@ Builds completely static HTML sites that you can host on GitHub pages, Amazon S3 #### Great themes available. -There's a stack of good looking themes included by default. Choose from bootstrap, readthedocs, ghostwriter, or any of the 12 bootswatch themes. +There's a stack of good looking themes included by default. Choose from bootstrap, readthedocs, ghostwriter, or any of the 12 bootswatch themes. #### Preview your site as you work. -The built-in devserver allows you to preview your documentation as your 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. +The built-in devserver allows you to preview your documentation as your 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. #### Easy to customize. @@ -47,23 +47,35 @@ You should now have the `mkdocs` command installed on your system. Run `mkdocs In order to run, mkdocs requires a single configuration file named `mkdocs.yml` to exist in the current directory. -An sed aeque munere facilisi, modus tractatos quo ei. Eu veniam tincidunt cum. +There are two required settings in the configuration file, `site_name`, and `pages`. Let's create a simple configuration file for our new project `MkLorum`: - site_name: 'Cat indexer' + site_name: 'MkLorum' pages: - ['index.md', 'Home'] - ['about.md', 'About'] -You documentation source files should all exist in a single directory. By default this directory should be named `docs`. +Your documentation source files should all exist in a single directory. By default this directory should be named `docs`. -Quo ex ceteros theophrastus, mel eius repudiandae an, has autem legendos ut. Eu quo moderatius interpretaris, pro ad homero tractatos cotidieque. His errem dictas instructior ad, tation causae ceteros ex eum. Nam falli dicunt te, mea et unum contentiones, ius noluisse rationibus cotidieque ei. + $ mkdir docs + +Now we need some documentation. The markdown files in our `docs` directory should correspond with the entries in the configuration file, so we need to create `index.md` and `about.md` files, and populate them with some markdown. + +As a shortcut, we can use the [`lorum-markdownum` API](https://github.com/jaspervdj/lorem-markdownum) to generate some markdown text automatically: + + $ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/index.md + $ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md + +When you're done the `docs` directory should look like this: $ ls docs about.md index.md -Quo ex ceteros theophrastus, mel eius repudiandae an, has autem legendos ut. Eu quo moderatius interpretaris, pro ad homero tractatos cotidieque. His errem dictas instructior ad, tation causae ceteros ex eum. Nam falli dicunt te, mea et unum contentiones, ius noluisse rationibus cotidieque ei. +Okay, we're ready to build our documentation now. 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 `mkdocs.yml` config file, and then running the `mkdocs serve` command: $ mkdocs serve + Running at: http://127.0.0.1:8000/ + +Open up [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your browser, and you'll see the index page being displayed. Mea dicta aliquid ornatus cu, duis sanctus disputationi his in. Rebum adolescens definiebas vis te. Ornatus noluisse mel te, modo utinam ea sit, putent omittantur quo ad. Ius ad dicta iusto, vel ne nonumy quaestio. diff --git a/mkdocs.yml b/mkdocs.yml index 3d20eb5d..65940a5d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,5 +11,5 @@ pages: - ['user-guide/configuration.md', 'User Guide', 'Configuration'] - ['about/license.md', 'About', 'License'] -theme_dir: 'theme' +theme: 'mkdocs' theme_center_lead: true diff --git a/mkdocs/config.py b/mkdocs/config.py index 8ee99702..885b455d 100644 --- a/mkdocs/config.py +++ b/mkdocs/config.py @@ -14,7 +14,7 @@ DEFAULT_CONFIG = { 'site_author': None, 'site_favicon': None, - 'theme': 'bootstrap', + 'theme': 'mkdocs', 'docs_dir': 'docs', 'site_dir': 'site', 'theme_dir': None, diff --git a/theme/base.html b/mkdocs/themes/mkdocs/base.html similarity index 100% rename from theme/base.html rename to mkdocs/themes/mkdocs/base.html diff --git a/theme/content.html b/mkdocs/themes/mkdocs/content.html similarity index 100% rename from theme/content.html rename to mkdocs/themes/mkdocs/content.html diff --git a/theme/css/base.css b/mkdocs/themes/mkdocs/css/base.css similarity index 100% rename from theme/css/base.css rename to mkdocs/themes/mkdocs/css/base.css diff --git a/theme/css/bootstrap-custom.min.css b/mkdocs/themes/mkdocs/css/bootstrap-custom.min.css similarity index 100% rename from theme/css/bootstrap-custom.min.css rename to mkdocs/themes/mkdocs/css/bootstrap-custom.min.css diff --git a/theme/css/font-awesome-4.0.3.css b/mkdocs/themes/mkdocs/css/font-awesome-4.0.3.css similarity index 100% rename from theme/css/font-awesome-4.0.3.css rename to mkdocs/themes/mkdocs/css/font-awesome-4.0.3.css diff --git a/theme/css/prettify-1.0.css b/mkdocs/themes/mkdocs/css/prettify-1.0.css similarity index 100% rename from theme/css/prettify-1.0.css rename to mkdocs/themes/mkdocs/css/prettify-1.0.css diff --git a/theme/fonts/fontawesome-webfont.eot b/mkdocs/themes/mkdocs/fonts/fontawesome-webfont.eot similarity index 100% rename from theme/fonts/fontawesome-webfont.eot rename to mkdocs/themes/mkdocs/fonts/fontawesome-webfont.eot diff --git a/theme/fonts/fontawesome-webfont.svg b/mkdocs/themes/mkdocs/fonts/fontawesome-webfont.svg similarity index 100% rename from theme/fonts/fontawesome-webfont.svg rename to mkdocs/themes/mkdocs/fonts/fontawesome-webfont.svg diff --git a/theme/fonts/fontawesome-webfont.ttf b/mkdocs/themes/mkdocs/fonts/fontawesome-webfont.ttf similarity index 100% rename from theme/fonts/fontawesome-webfont.ttf rename to mkdocs/themes/mkdocs/fonts/fontawesome-webfont.ttf diff --git a/theme/fonts/fontawesome-webfont.woff b/mkdocs/themes/mkdocs/fonts/fontawesome-webfont.woff similarity index 100% rename from theme/fonts/fontawesome-webfont.woff rename to mkdocs/themes/mkdocs/fonts/fontawesome-webfont.woff diff --git a/theme/img/favicon.ico b/mkdocs/themes/mkdocs/img/favicon.ico similarity index 100% rename from theme/img/favicon.ico rename to mkdocs/themes/mkdocs/img/favicon.ico diff --git a/theme/img/grid.png b/mkdocs/themes/mkdocs/img/grid.png similarity index 100% rename from theme/img/grid.png rename to mkdocs/themes/mkdocs/img/grid.png diff --git a/theme/js/base.js b/mkdocs/themes/mkdocs/js/base.js similarity index 100% rename from theme/js/base.js rename to mkdocs/themes/mkdocs/js/base.js diff --git a/theme/js/bootstrap-3.0.3.min.js b/mkdocs/themes/mkdocs/js/bootstrap-3.0.3.min.js similarity index 100% rename from theme/js/bootstrap-3.0.3.min.js rename to mkdocs/themes/mkdocs/js/bootstrap-3.0.3.min.js diff --git a/theme/js/prettify-1.0.min.js b/mkdocs/themes/mkdocs/js/prettify-1.0.min.js similarity index 100% rename from theme/js/prettify-1.0.min.js rename to mkdocs/themes/mkdocs/js/prettify-1.0.min.js diff --git a/theme/nav.html b/mkdocs/themes/mkdocs/nav.html similarity index 100% rename from theme/nav.html rename to mkdocs/themes/mkdocs/nav.html diff --git a/theme/search.html b/mkdocs/themes/mkdocs/search.html similarity index 100% rename from theme/search.html rename to mkdocs/themes/mkdocs/search.html diff --git a/theme/toc.html b/mkdocs/themes/mkdocs/toc.html similarity index 100% rename from theme/toc.html rename to mkdocs/themes/mkdocs/toc.html