Permalink
Browse files

Merge pull request #530 from d0ugal/package-themes

Move builtin themes to external packages other than MkDocs and ReadTheDocs
  • Loading branch information...
d0ugal committed Jun 27, 2015
2 parents 8172bcb + 764b24b commit ff05df30dd2de8840fb185363afa41a5517a69ef
Showing with 764 additions and 28,724 deletions.
  1. +3 −1 .travis.yml
  2. +3 −1 MANIFEST.in
  3. +7 −3 appveyor.yml
  4. +29 −1 docs/about/release-notes.md
  5. +4 −0 docs/css/extra.css
  6. +50 −27 docs/index.md
  7. +417 −0 docs/user-guide/custom-themes.md
  8. +55 −236 docs/user-guide/styling-your-docs.md
  9. +82 −58 docs/user-guide/writing-your-docs.md
  10. +2 −1 mkdocs.yml
  11. +1 −1 mkdocs/config/config_options.py
  12. +2 −2 mkdocs/tests/config/config_tests.py
  13. +1 −1 mkdocs/tests/integration.py
  14. +41 −1 mkdocs/tests/utils/utils_tests.py
  15. 0 mkdocs/themes/__init__.py
  16. +0 −67 mkdocs/themes/amelia/base.html
  17. +0 −9 mkdocs/themes/amelia/content.html
  18. +0 −113 mkdocs/themes/amelia/css/base.css
  19. +0 −1 mkdocs/themes/amelia/css/bootstrap-custom.min.css
  20. +0 −1,338 mkdocs/themes/amelia/css/font-awesome-4.0.3.css
  21. +0 −125 mkdocs/themes/amelia/css/highlight.css
  22. BIN mkdocs/themes/amelia/fonts/fontawesome-webfont.eot
  23. +0 −414 mkdocs/themes/amelia/fonts/fontawesome-webfont.svg
  24. BIN mkdocs/themes/amelia/fonts/fontawesome-webfont.ttf
  25. BIN mkdocs/themes/amelia/fonts/fontawesome-webfont.woff
  26. BIN mkdocs/themes/amelia/img/favicon.ico
  27. +0 −19 mkdocs/themes/amelia/js/base.js
  28. +0 −7 mkdocs/themes/amelia/js/bootstrap-3.0.3.min.js
  29. +0 −2 mkdocs/themes/amelia/js/highlight.pack.js
  30. +0 −6 mkdocs/themes/amelia/js/jquery-1.10.2.min.js
  31. +0 −69 mkdocs/themes/amelia/nav.html
  32. +0 −10 mkdocs/themes/amelia/toc.html
  33. +0 −68 mkdocs/themes/bootstrap/base.html
  34. +0 −9 mkdocs/themes/bootstrap/content.html
  35. +0 −113 mkdocs/themes/bootstrap/css/base.css
  36. +0 −7 mkdocs/themes/bootstrap/css/bootstrap-3.0.3.min.css
  37. +0 −1,338 mkdocs/themes/bootstrap/css/font-awesome-4.0.3.css
  38. +0 −125 mkdocs/themes/bootstrap/css/highlight.css
  39. BIN mkdocs/themes/bootstrap/fonts/fontawesome-webfont.eot
  40. +0 −414 mkdocs/themes/bootstrap/fonts/fontawesome-webfont.svg
  41. BIN mkdocs/themes/bootstrap/fonts/fontawesome-webfont.ttf
  42. BIN mkdocs/themes/bootstrap/fonts/fontawesome-webfont.woff
  43. BIN mkdocs/themes/bootstrap/img/favicon.ico
  44. +0 −20 mkdocs/themes/bootstrap/js/base.js
  45. +0 −7 mkdocs/themes/bootstrap/js/bootstrap-3.0.3.min.js
  46. +0 −2 mkdocs/themes/bootstrap/js/highlight.pack.js
  47. +0 −6 mkdocs/themes/bootstrap/js/jquery-1.10.2.min.js
  48. +0 −69 mkdocs/themes/bootstrap/nav.html
  49. +0 −10 mkdocs/themes/bootstrap/toc.html
  50. +0 −67 mkdocs/themes/cerulean/base.html
  51. +0 −9 mkdocs/themes/cerulean/content.html
  52. +0 −113 mkdocs/themes/cerulean/css/base.css
  53. +0 −1 mkdocs/themes/cerulean/css/bootstrap-custom.min.css
  54. +0 −1,338 mkdocs/themes/cerulean/css/font-awesome-4.0.3.css
  55. +0 −125 mkdocs/themes/cerulean/css/highlight.css
  56. BIN mkdocs/themes/cerulean/fonts/fontawesome-webfont.eot
  57. +0 −414 mkdocs/themes/cerulean/fonts/fontawesome-webfont.svg
  58. BIN mkdocs/themes/cerulean/fonts/fontawesome-webfont.ttf
  59. BIN mkdocs/themes/cerulean/fonts/fontawesome-webfont.woff
  60. BIN mkdocs/themes/cerulean/img/favicon.ico
  61. +0 −20 mkdocs/themes/cerulean/js/base.js
  62. +0 −7 mkdocs/themes/cerulean/js/bootstrap-3.0.3.min.js
  63. +0 −2 mkdocs/themes/cerulean/js/highlight.pack.js
  64. +0 −6 mkdocs/themes/cerulean/js/jquery-1.10.2.min.js
  65. +0 −69 mkdocs/themes/cerulean/nav.html
  66. +0 −10 mkdocs/themes/cerulean/toc.html
  67. +0 −67 mkdocs/themes/cosmo/base.html
  68. +0 −9 mkdocs/themes/cosmo/content.html
  69. +0 −113 mkdocs/themes/cosmo/css/base.css
  70. +0 −1 mkdocs/themes/cosmo/css/bootstrap-custom.min.css
  71. +0 −1,338 mkdocs/themes/cosmo/css/font-awesome-4.0.3.css
  72. +0 −125 mkdocs/themes/cosmo/css/highlight.css
  73. BIN mkdocs/themes/cosmo/fonts/fontawesome-webfont.eot
  74. +0 −414 mkdocs/themes/cosmo/fonts/fontawesome-webfont.svg
  75. BIN mkdocs/themes/cosmo/fonts/fontawesome-webfont.ttf
  76. BIN mkdocs/themes/cosmo/fonts/fontawesome-webfont.woff
  77. BIN mkdocs/themes/cosmo/img/favicon.ico
  78. +0 −20 mkdocs/themes/cosmo/js/base.js
  79. +0 −7 mkdocs/themes/cosmo/js/bootstrap-3.0.3.min.js
  80. +0 −2 mkdocs/themes/cosmo/js/highlight.pack.js
  81. +0 −6 mkdocs/themes/cosmo/js/jquery-1.10.2.min.js
  82. +0 −69 mkdocs/themes/cosmo/nav.html
  83. +0 −10 mkdocs/themes/cosmo/toc.html
  84. +0 −67 mkdocs/themes/cyborg/base.html
  85. +0 −9 mkdocs/themes/cyborg/content.html
  86. +0 −113 mkdocs/themes/cyborg/css/base.css
  87. +0 −1 mkdocs/themes/cyborg/css/bootstrap-custom.min.css
  88. +0 −1,338 mkdocs/themes/cyborg/css/font-awesome-4.0.3.css
  89. +0 −125 mkdocs/themes/cyborg/css/highlight.css
  90. BIN mkdocs/themes/cyborg/fonts/fontawesome-webfont.eot
  91. +0 −414 mkdocs/themes/cyborg/fonts/fontawesome-webfont.svg
  92. BIN mkdocs/themes/cyborg/fonts/fontawesome-webfont.ttf
  93. BIN mkdocs/themes/cyborg/fonts/fontawesome-webfont.woff
  94. BIN mkdocs/themes/cyborg/img/favicon.ico
  95. +0 −20 mkdocs/themes/cyborg/js/base.js
  96. +0 −7 mkdocs/themes/cyborg/js/bootstrap-3.0.3.min.js
  97. +0 −2 mkdocs/themes/cyborg/js/highlight.pack.js
  98. +0 −6 mkdocs/themes/cyborg/js/jquery-1.10.2.min.js
  99. +0 −69 mkdocs/themes/cyborg/nav.html
  100. +0 −10 mkdocs/themes/cyborg/toc.html
  101. +0 −67 mkdocs/themes/flatly/base.html
  102. +0 −9 mkdocs/themes/flatly/content.html
  103. +0 −113 mkdocs/themes/flatly/css/base.css
  104. +0 −1 mkdocs/themes/flatly/css/bootstrap-custom.min.css
  105. +0 −1,338 mkdocs/themes/flatly/css/font-awesome-4.0.3.css
  106. +0 −125 mkdocs/themes/flatly/css/highlight.css
  107. BIN mkdocs/themes/flatly/fonts/fontawesome-webfont.eot
  108. +0 −414 mkdocs/themes/flatly/fonts/fontawesome-webfont.svg
  109. BIN mkdocs/themes/flatly/fonts/fontawesome-webfont.ttf
  110. BIN mkdocs/themes/flatly/fonts/fontawesome-webfont.woff
  111. BIN mkdocs/themes/flatly/img/favicon.ico
  112. +0 −20 mkdocs/themes/flatly/js/base.js
  113. +0 −7 mkdocs/themes/flatly/js/bootstrap-3.0.3.min.js
  114. +0 −2 mkdocs/themes/flatly/js/highlight.pack.js
  115. +0 −6 mkdocs/themes/flatly/js/jquery-1.10.2.min.js
  116. +0 −69 mkdocs/themes/flatly/nav.html
  117. +0 −10 mkdocs/themes/flatly/toc.html
  118. +0 −67 mkdocs/themes/journal/base.html
  119. +0 −9 mkdocs/themes/journal/content.html
  120. +0 −113 mkdocs/themes/journal/css/base.css
  121. +0 −1 mkdocs/themes/journal/css/bootstrap-custom.min.css
  122. +0 −1,338 mkdocs/themes/journal/css/font-awesome-4.0.3.css
  123. +0 −125 mkdocs/themes/journal/css/highlight.css
  124. BIN mkdocs/themes/journal/fonts/fontawesome-webfont.eot
  125. +0 −414 mkdocs/themes/journal/fonts/fontawesome-webfont.svg
  126. BIN mkdocs/themes/journal/fonts/fontawesome-webfont.ttf
  127. BIN mkdocs/themes/journal/fonts/fontawesome-webfont.woff
  128. BIN mkdocs/themes/journal/img/favicon.ico
  129. +0 −20 mkdocs/themes/journal/js/base.js
  130. +0 −7 mkdocs/themes/journal/js/bootstrap-3.0.3.min.js
  131. +0 −2 mkdocs/themes/journal/js/highlight.pack.js
  132. +0 −6 mkdocs/themes/journal/js/jquery-1.10.2.min.js
  133. +0 −69 mkdocs/themes/journal/nav.html
  134. +0 −10 mkdocs/themes/journal/toc.html
  135. 0 mkdocs/themes/mkdocs/__init__.py
  136. +0 −67 mkdocs/themes/readable/base.html
  137. +0 −9 mkdocs/themes/readable/content.html
  138. +0 −113 mkdocs/themes/readable/css/base.css
  139. +0 −1 mkdocs/themes/readable/css/bootstrap-custom.min.css
  140. +0 −1,338 mkdocs/themes/readable/css/font-awesome-4.0.3.css
  141. +0 −125 mkdocs/themes/readable/css/highlight.css
  142. BIN mkdocs/themes/readable/fonts/fontawesome-webfont.eot
  143. +0 −414 mkdocs/themes/readable/fonts/fontawesome-webfont.svg
  144. BIN mkdocs/themes/readable/fonts/fontawesome-webfont.ttf
  145. BIN mkdocs/themes/readable/fonts/fontawesome-webfont.woff
  146. BIN mkdocs/themes/readable/img/favicon.ico
  147. +0 −20 mkdocs/themes/readable/js/base.js
  148. +0 −7 mkdocs/themes/readable/js/bootstrap-3.0.3.min.js
  149. +0 −2 mkdocs/themes/readable/js/highlight.pack.js
  150. +0 −6 mkdocs/themes/readable/js/jquery-1.10.2.min.js
  151. +0 −69 mkdocs/themes/readable/nav.html
  152. +0 −10 mkdocs/themes/readable/toc.html
  153. 0 mkdocs/themes/readthedocs/__init__.py
  154. +0 −67 mkdocs/themes/simplex/base.html
  155. +0 −9 mkdocs/themes/simplex/content.html
  156. +0 −113 mkdocs/themes/simplex/css/base.css
  157. +0 −1 mkdocs/themes/simplex/css/bootstrap-custom.min.css
  158. +0 −1,338 mkdocs/themes/simplex/css/font-awesome-4.0.3.css
  159. +0 −125 mkdocs/themes/simplex/css/highlight.css
  160. BIN mkdocs/themes/simplex/fonts/fontawesome-webfont.eot
  161. +0 −414 mkdocs/themes/simplex/fonts/fontawesome-webfont.svg
  162. BIN mkdocs/themes/simplex/fonts/fontawesome-webfont.ttf
  163. BIN mkdocs/themes/simplex/fonts/fontawesome-webfont.woff
  164. BIN mkdocs/themes/simplex/img/favicon.ico
  165. +0 −20 mkdocs/themes/simplex/js/base.js
  166. +0 −7 mkdocs/themes/simplex/js/bootstrap-3.0.3.min.js
  167. +0 −2 mkdocs/themes/simplex/js/highlight.pack.js
  168. +0 −6 mkdocs/themes/simplex/js/jquery-1.10.2.min.js
  169. +0 −69 mkdocs/themes/simplex/nav.html
  170. +0 −10 mkdocs/themes/simplex/toc.html
  171. +0 −67 mkdocs/themes/slate/base.html
  172. +0 −9 mkdocs/themes/slate/content.html
  173. +0 −113 mkdocs/themes/slate/css/base.css
  174. +0 −1 mkdocs/themes/slate/css/bootstrap-custom.min.css
  175. +0 −1,338 mkdocs/themes/slate/css/font-awesome-4.0.3.css
  176. +0 −125 mkdocs/themes/slate/css/highlight.css
  177. BIN mkdocs/themes/slate/fonts/fontawesome-webfont.eot
  178. +0 −414 mkdocs/themes/slate/fonts/fontawesome-webfont.svg
  179. BIN mkdocs/themes/slate/fonts/fontawesome-webfont.ttf
  180. BIN mkdocs/themes/slate/fonts/fontawesome-webfont.woff
  181. BIN mkdocs/themes/slate/img/favicon.ico
  182. +0 −20 mkdocs/themes/slate/js/base.js
  183. +0 −7 mkdocs/themes/slate/js/bootstrap-3.0.3.min.js
  184. +0 −2 mkdocs/themes/slate/js/highlight.pack.js
  185. +0 −6 mkdocs/themes/slate/js/jquery-1.10.2.min.js
  186. +0 −69 mkdocs/themes/slate/nav.html
  187. +0 −10 mkdocs/themes/slate/toc.html
  188. +0 −67 mkdocs/themes/spacelab/base.html
  189. +0 −9 mkdocs/themes/spacelab/content.html
  190. +0 −113 mkdocs/themes/spacelab/css/base.css
  191. +0 −1 mkdocs/themes/spacelab/css/bootstrap-custom.min.css
  192. +0 −1,338 mkdocs/themes/spacelab/css/font-awesome-4.0.3.css
  193. +0 −125 mkdocs/themes/spacelab/css/highlight.css
  194. BIN mkdocs/themes/spacelab/fonts/fontawesome-webfont.eot
  195. +0 −414 mkdocs/themes/spacelab/fonts/fontawesome-webfont.svg
  196. BIN mkdocs/themes/spacelab/fonts/fontawesome-webfont.ttf
  197. BIN mkdocs/themes/spacelab/fonts/fontawesome-webfont.woff
  198. BIN mkdocs/themes/spacelab/img/favicon.ico
  199. +0 −20 mkdocs/themes/spacelab/js/base.js
  200. +0 −7 mkdocs/themes/spacelab/js/bootstrap-3.0.3.min.js
  201. +0 −2 mkdocs/themes/spacelab/js/highlight.pack.js
  202. +0 −6 mkdocs/themes/spacelab/js/jquery-1.10.2.min.js
  203. +0 −69 mkdocs/themes/spacelab/nav.html
  204. +0 −10 mkdocs/themes/spacelab/toc.html
  205. +0 −67 mkdocs/themes/united/base.html
  206. +0 −9 mkdocs/themes/united/content.html
  207. +0 −113 mkdocs/themes/united/css/base.css
  208. +0 −1 mkdocs/themes/united/css/bootstrap-custom.min.css
  209. +0 −1,338 mkdocs/themes/united/css/font-awesome-4.0.3.css
  210. +0 −125 mkdocs/themes/united/css/highlight.css
  211. BIN mkdocs/themes/united/fonts/fontawesome-webfont.eot
  212. +0 −414 mkdocs/themes/united/fonts/fontawesome-webfont.svg
  213. BIN mkdocs/themes/united/fonts/fontawesome-webfont.ttf
  214. BIN mkdocs/themes/united/fonts/fontawesome-webfont.woff
  215. BIN mkdocs/themes/united/img/favicon.ico
  216. +0 −20 mkdocs/themes/united/js/base.js
  217. +0 −7 mkdocs/themes/united/js/bootstrap-3.0.3.min.js
  218. +0 −2 mkdocs/themes/united/js/highlight.pack.js
  219. +0 −6 mkdocs/themes/united/js/jquery-1.10.2.min.js
  220. +0 −69 mkdocs/themes/united/nav.html
  221. +0 −10 mkdocs/themes/united/toc.html
  222. +0 −67 mkdocs/themes/yeti/base.html
  223. +0 −9 mkdocs/themes/yeti/content.html
  224. +0 −113 mkdocs/themes/yeti/css/base.css
  225. +0 −1 mkdocs/themes/yeti/css/bootstrap-custom.min.css
  226. +0 −1,338 mkdocs/themes/yeti/css/font-awesome-4.0.3.css
  227. +0 −125 mkdocs/themes/yeti/css/highlight.css
  228. BIN mkdocs/themes/yeti/fonts/fontawesome-webfont.eot
  229. +0 −414 mkdocs/themes/yeti/fonts/fontawesome-webfont.svg
  230. BIN mkdocs/themes/yeti/fonts/fontawesome-webfont.ttf
  231. BIN mkdocs/themes/yeti/fonts/fontawesome-webfont.woff
  232. BIN mkdocs/themes/yeti/img/favicon.ico
  233. +0 −20 mkdocs/themes/yeti/js/base.js
  234. +0 −7 mkdocs/themes/yeti/js/bootstrap-3.0.3.min.js
  235. +0 −2 mkdocs/themes/yeti/js/highlight.pack.js
  236. +0 −6 mkdocs/themes/yeti/js/jquery-1.10.2.min.js
  237. +0 −69 mkdocs/themes/yeti/nav.html
  238. +0 −10 mkdocs/themes/yeti/toc.html
  239. +55 −14 mkdocs/utils/__init__.py
  240. +2 −0 requirements/project-min.txt
  241. +2 −0 requirements/project.txt
  242. +8 −18 setup.py
@@ -16,7 +16,9 @@ env:
- TOXENV=flake8
install:
- pip install tox
script: tox
script:
- git clean -f -d -x
- tox
matrix:
fast_finish: true
before_install: pip install codecov
@@ -1,3 +1,5 @@
recursive-include mkdocs/themes *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff
include README.md
include LICENSE.md
recursive-include mkdocs *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff *.xml
recursive-exclude * __pycache__
recursive-exclude * *.py[co]
@@ -1,12 +1,15 @@
build: false
environment:
matrix:
- TOXENV: py27-unittests
- TOXENV: py33-unittests
- TOXENV: py34-unittests
- TOXENV: py27-integration
- TOXENV: py27-min-req
- TOXENV: py27-unittests
- TOXENV: py33-integration
- TOXENV: py33-min-req
- TOXENV: py33-unittests
- TOXENV: py34-integration
- TOXENV: py34-min-req
- TOXENV: py34-unittests
- TOXENV: flake8
init:
- "ECHO %TOXENV%"
@@ -18,6 +21,7 @@ install:
- "c:\\python27\\python c:\\get-pip.py"
- "c:\\python27\\Scripts\\pip install tox"
test_script:
- "git clean -f -d -x"
- "c:\\python27\\Scripts\\tox --version"
- "c:\\python27\\Scripts\\pip --version"
- "c:\\python27\\Scripts\\tox"
@@ -16,14 +16,42 @@ You can determine your currently installed version using `mkdocs --version`:

## Version 0.15.0 (2015-??-??)

### Major Additions

#### Add support for installable themes

MkDocs now supports themes that are distributed via Python packages. With this
addition, the Bootstrap and Bootswatch themes have been moved to external git
repositories and python packages. See their individual documentation for more
details about these specific themes.

- [MkDocs Bootstrap]
- [MkDocs Bootswatch]

[MkDocs Bootstrap]: http://mkdocs.github.io/mkdocs-bootstrap/
[MkDocs Bootswatch]: http://mkdocs.github.io/mkdocs-bootswatch/

They will be included with MkDocs by default until the 1.0 release. After that
they will be installable with pip: `pip install mkdocs-bootstrap` and `pip
install mkdocs-bootswatch`

See the documentation for [Styling your docs] for more information about using
and customising themes and [Custom themes] for creating and distributing new
themes

[Styling your docs]: /user-guide/styling-your-docs.md
[Custom themes]: /user-guide/custom-themes.md

### Other Changes and Additions

* Fix issues when using absolute links to Markdown files. (#628)
* Add support for [site_description] and [site_author] to the [ReadTheDocs]
theme. (#631)
* Bugfix: Ensure consistent ordering of auto-populated pages. (#638)

[site_description]: /user-guide/configuration.md#site_description
[site_author]: /user-guide/configuration.md#site_author
[ReadTheDocs]: /user-guide/styling-your-docs.md#read-the-docs
[ReadTheDocs]: /user-guide/styling-your-docs.md#readthedocs

## Version 0.14.0 (2015-06-09)

@@ -15,3 +15,7 @@ div.col-md-9 p.admonition-title:first-of-type {
div.col-md-9 h1:first-of-type .headerlink {
display: none;
}

code.no-highlight {
color: black;
}
@@ -38,23 +38,29 @@ Get your project documentation looking just the way you want it by customizing t

In order to install MkDocs you'll need [Python] installed on your system, as well as the Python package manager, [pip]. You can check if you have these already installed like so:

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
```bash
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
```

MkDocs supports Python 2.6, 2.7, 3.3 and 3.4.

On Windows we recommend that you install Python and pip with [Chocolatey].

Install the `mkdocs` package using pip:

$ pip install mkdocs
```bash
$ pip install mkdocs
```

You should now have the `mkdocs` command installed on your system. Run `mkdocs --version` to check that everything worked okay.

$ mkdocs --version
mkdocs, version 0.14.0
```bash
$ mkdocs --version
mkdocs, version 0.14.0
```

---

@@ -63,8 +69,10 @@ You should now have the `mkdocs` command installed on your system. Run `mkdocs

Getting started is super easy.

$ mkdocs new my-project
$ cd my-project
```bash
$ mkdocs new my-project
$ cd my-project
```

Let's take a moment to review the initial project that's been created for us.

@@ -74,8 +82,10 @@ There's a single configuration file named `mkdocs.yml`, and a folder named `docs

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/
```bash
$ 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:

@@ -99,27 +109,32 @@ Go ahead and edit the `doc/index.md` document, and change the initial heading to

Let's also add a second page to our documentation:

$ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
```bash
$ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
```

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:

site_name: MkLorum
pages:
- Home: index.md
- About: about.md
```no-highlight
site_name: MkLorum
pages:
- Home: index.md
- About: about.md
```

Refresh the browser and you'll now see a navigation bar with `Home` and `About` headers.

## Theming our documentation

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 `mkdocs.yml` file to the following:

site_name: MkLorum
pages:
- Home: index.md
- About: about.md
theme: readthedocs

```no-highlight
site_name: MkLorum
pages:
- Home: index.md
- About: about.md
theme: readthedocs
```

Refresh the browser again, and you'll now see the ReadTheDocs theme being used.

@@ -129,24 +144,32 @@ Refresh the browser again, and you'll now see the ReadTheDocs theme being used.

That's looking good. We're ready to deploy the first pass of our `MkLorum` documentation now. Let's build the documentation.

$ mkdocs build
```bash
$ mkdocs build
```

This will create a new directory, named `site`. Let's take a look inside the directory:

$ ls site
about css fonts img index.html js
```bash
$ ls site
about css fonts img index.html js
```

Notice that our source documentation has been output as two HTML files named `index.html` and `about/index.html`. We also have various other media that's been copied into the `site` directory as part of the documentation theme.

If you're using source code control such as `git` you probably don't want to check your documentation builds into the repository. Add a line containing `site/` to your `.gitignore` file.

$ echo "site/" >> .gitignore
```bash
$ echo "site/" >> .gitignore
```

If you're using another source code control you'll want to check it's documentation on how to ignore specific directories.

After some time, files may be removed from the documentation but they will still reside in the `site` directory. To remove those stale files, just run mkdocs with the `--clean` switch.

$ mkdocs build --clean
```bash
$ mkdocs build --clean
```


## Deploying
Oops, something went wrong.

0 comments on commit ff05df3

Please sign in to comment.