From 7ef39aa4e2406d8f2e0159fbbc1fd4ffe0a36a97 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Tue, 14 Apr 2015 08:30:44 +0100 Subject: [PATCH] Some minor updates to the documentation - Added a small section about where to get help - Updated link to the contributing guide - Improved some o the code highlighting --- CONTRIBUTING.md | 2 +- docs/about/contributing.md | 10 ++++++- docs/index.md | 22 +++++++++++---- docs/user-guide/writing-your-docs.md | 42 +++++++++++++++------------- 4 files changed, 50 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bff8d52..effb1105 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,4 +3,4 @@ See the contributing guide in the documentation for an introduction to contributing to MkDocs. - https://github.com/mkdocs/mkdocs/blob/master/docs/about/contributing.md + http://www.mkdocs.org/about/contributing/ diff --git a/docs/about/contributing.md b/docs/about/contributing.md index 5797ff36..793be7e5 100644 --- a/docs/about/contributing.md +++ b/docs/about/contributing.md @@ -10,13 +10,21 @@ can be made in a number of ways, a few examples are: - Documentation improvements - Bug reports and patch reviews +## Reporting an issue? + +Please include as much detail as you can. Let us know your +platform and MkDocs version. If the problem is visual (for +example a theme or design issue) please add a screenshot and if +you get an error please include the the full error and traceback. + + ## Installing for development First you'll need to fork and clone the repository. Once you have a local copy, run the following command. It is recommended that you do this within a [virtualenv](virtualenv). -```no-highlight +```text pip install --editable . ``` diff --git a/docs/index.md b/docs/index.md index d82dabb4..030286d7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ MkDocs is a **fast**, **simple** and **downright gorgeous** static site generato **MkDocs is currently still in development.** -We're progressing quickly, but the documentation still needs filling in, and theres a few rough edges. The 1.0 release is planned to arrive in the next few months. +We're progressing quickly, but the documentation still needs filling in, and there are a few rough edges. The 1.0 release is planned to arrive in the next few months. --- @@ -36,7 +36,7 @@ Get your project documentation looking just the way you want it by customizing t ## Installation -In order to install MkDocs you'll need [Python][python] installed on your system, as well as the Python package manager, [pip][pip]. You can check if you have these already installed like so: +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 @@ -45,7 +45,7 @@ In order to install MkDocs you'll need [Python][python] installed on your system MkDocs supports Python 2.6, 2.7, 3.3 and 3.4. -On Windows we recommend that you install Python and pip with [Chocolatey](https://chocolatey.org/). +On Windows we recommend that you install Python and pip with [Chocolatey]. Install the `mkdocs` package using pip: @@ -58,6 +58,7 @@ You should now have the `mkdocs` command installed on your system. Run `mkdocs --- + ## Getting started Getting started is super easy. @@ -150,9 +151,20 @@ After some time, files may be removed from the documentation but they will still $ mkdocs build --clean + ## Deploying -The documentation site that we've just built only uses static files so you'll be able to host it from pretty much anywhere. [GitHub project pages](https://help.github.com/articles/creating-project-pages-manually) and [Amazon S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) are good hosting options. Upload the contents of the entire `site` directory to wherever you're hosting your website from and you're done. +The documentation site that we've just built only uses static files so you'll be able to host it from pretty much anywhere. [GitHub project pages] and [Amazon S3] are good hosting options. Upload the contents of the entire `site` directory to wherever you're hosting your website from and you're done. -[python]: https://www.python.org/ + +## Getting help + +To get help with MkDocs, please use the [discussion group], [GitHub issues] or the MkDocs IRC channel `#mkdocs` on freenode. + +[Amazon S3]: http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html +[Chocolatey]: https://chocolatey.org/ +[discussion group]: https://groups.google.com/forum/#!forum/mkdocs +[GitHub issues]: https://github.com/mkdocs/mkdocs/issues +[GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually [pip]: http://pip.readthedocs.org/en/latest/installing.html +[Python]: https://www.python.org/ diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md index b9f0cdbe..ed63cfbc 100644 --- a/docs/user-guide/writing-your-docs.md +++ b/docs/user-guide/writing-your-docs.md @@ -130,24 +130,30 @@ At mel verear persius torquatos, his dolores sensibus id, alia urbanitas in usu. A simple table looks like this: - First Header | Second Header | Third Header - ------------ | ------------- | ------------ - Content Cell | Content Cell | Content Cell - Content Cell | Content Cell | Content Cell +```text +First Header | Second Header | Third Header +------------ | ------------- | ------------ +Content Cell | Content Cell | Content Cell +Content Cell | Content Cell | Content Cell +``` If you wish, you can add a leading and tailing pipe to each line of the table: - | First Header | Second Header | Third Header | - | ------------ | ------------- | ------------ | - | Content Cell | Content Cell | Content Cell | - | Content Cell | Content Cell | Content Cell | +```text +| First Header | Second Header | Third Header | +| ------------ | ------------- | ------------ | +| Content Cell | Content Cell | Content Cell | +| Content Cell | Content Cell | Content Cell | +``` Specify alignment for each column by adding colons to separator lines: - First Header | Second Header | Third Header - :----------- | :-----------: | -----------: - Left | Center | Right - Left | Center | Right +```text +First Header | Second Header | Third Header +:----------- | :-----------: | -----------: +Left | Center | Right +Left | Center | Right +``` #### Fenced code blocks @@ -161,11 +167,9 @@ Start with a line containing 3 or more backtick \` characters, and ends with the block. ``` - + ```python + def fn(): + pass + ```