From c61a6179f0ac43760b20116759faefc825e90ddb Mon Sep 17 00:00:00 2001 From: squidfunk Date: Thu, 12 Jan 2017 20:15:30 +0100 Subject: [PATCH] Updated documentation --- .gitignore | 2 +- CHANGELOG | 2 +- README.md | 2 +- docs/contributing.md | 4 +- docs/customization.md | 2 +- docs/extensions/admonition.md | 16 ++++- docs/extensions/codehilite.md | 6 +- docs/extensions/footnotes.md | 2 +- docs/extensions/pymdown.md | 16 ++--- docs/getting-started.md | 117 +++++++++++++++++----------------- docs/index.md | 37 +---------- docs/release-notes.md | 2 +- mkdocs.yml | 5 +- package.json | 2 +- setup.py | 2 +- 15 files changed, 97 insertions(+), 120 deletions(-) diff --git a/.gitignore b/.gitignore index 91cc6765a..c6cfbd09f 100644 --- a/.gitignore +++ b/.gitignore @@ -18,7 +18,7 @@ # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS # IN THE SOFTWARE. -# Mac OS X internals +# macOS internals .DS_Store # NPM-related diff --git a/CHANGELOG b/CHANGELOG index b84231628..bc7774d1e 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -7,7 +7,7 @@ mkdocs-material-1.0.0 (2017-01-13) * Introduced git-hooks for better development workflow * Rewrite of CSS using the BEM methodology and SassDoc guidelines * Rewrite of JavaScript using ES6 and Babel as a transpiler - * Rewrite of Admonition, Permalinks and Codehilite integration + * Rewrite of Admonition, Permalinks and CodeHilite integration * Rewrite of the complete typographical system * Rewrite of Gulp asset pipeline in ES6 and separation of tasks * Removed Bower as a dependency in favor of NPM diff --git a/README.md b/README.md index 78ca711a3..66d3c71e6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Codacy][codacy-image]][codacy-link] [![PyPI][pypi-image]][pypi-link] -A material design theme for [MkDocs](http://www.mkdocs.org). +A Material Design theme for [MkDocs](http://www.mkdocs.org). TBD: [![_](docs/images/screen.png)](http://squidfunk.github.io/mkdocs-material/) diff --git a/docs/contributing.md b/docs/contributing.md index 8c3bcf7fa..6cf8182db 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -30,12 +30,12 @@ proposal for your work first, to be sure that it is of use for everyone, as the Material theme is highly opinionated. Please consider what kind of change it is: -* For a **Major Feature**, first open an issue and outline your proposal so +* For a **major feature**, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project. -* **Small Features** and bugs can be crafted and directly submitted as a Pull +* **Small features and bugs** can be crafted and directly submitted as a Pull Request. However, there is no guarantee that your feature will make it into the master, as it's always a matter of opinion whether if benefits the overall functionality of the theme. diff --git a/docs/customization.md b/docs/customization.md index a06872c7f..3b6311cf7 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -35,7 +35,7 @@ extra_css: Spin up the development server with `mkdocs serve` and start typing your changes in your additional stylesheet file – you can see them instantly after -saving, as the MkDocs development server implements live reloading. Cool, huh? +saving, as the MkDocs development server implements live reloading. ### Additional JavaScript diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md index 4a678734e..e43d2fa69 100644 --- a/docs/extensions/admonition.md +++ b/docs/extensions/admonition.md @@ -34,6 +34,7 @@ Example: Result: !!! note + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -42,8 +43,8 @@ Result: ### Changing the title -By default, the block title will equal the type qualifier. However, it can -easily be changed by adding a quoted string after the type qualifier. +By default, the block title will equal the type qualifier in titlecase. However, +it can easily be changed by adding a quoted string after the type qualifier. Example: @@ -57,6 +58,7 @@ Example: Result: !!! note "Phasellus posuere in sem ut cursus" + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -78,6 +80,7 @@ Example: Result: !!! note "" + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -100,6 +103,7 @@ blocks. Example: !!! note + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -147,6 +151,7 @@ Example: Result: !!! note + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -170,6 +175,7 @@ Example: Result: !!! summary + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -193,6 +199,7 @@ Example: Result: !!! tip + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -217,6 +224,7 @@ Example: Result: !!! success + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -241,6 +249,7 @@ Example: Result: !!! warning + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -265,6 +274,7 @@ Example: Result: !!! failure + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -289,6 +299,7 @@ Example: Result: !!! danger + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. @@ -312,6 +323,7 @@ Example: Result: !!! bug + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. diff --git a/docs/extensions/codehilite.md b/docs/extensions/codehilite.md index cd26c8ed5..c5367aa5f 100644 --- a/docs/extensions/codehilite.md +++ b/docs/extensions/codehilite.md @@ -1,7 +1,7 @@ # CodeHilite -[CodeHilite][1] is an extension that adds syntax highlighting to codeblocks and -is included in the standard Markdown library. The highlighting process is +[CodeHilite][1] is an extension that adds syntax highlighting to code blocks +and is included in the standard Markdown library. The highlighting process is executed during compilation of the Markdown file. [1]: https://pythonhosted.org/Markdown/extensions/code_hilite.html @@ -621,7 +621,7 @@ module.exports = _extends(exports['default'], exports); { "name": "mkdocs-material", "version": "0.2.4", - "description": "A material design theme for MkDocs", + "description": "A Material Design theme for MkDocs", "homepage": "http://squidfunk.github.io/mkdocs-material/", "authors": [ "squidfunk " diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md index 7f080547d..a33458bc7 100644 --- a/docs/extensions/footnotes.md +++ b/docs/extensions/footnotes.md @@ -39,7 +39,7 @@ Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2] ### Inserting the content -The footnote content is also initiated with a label, which must match the label +The footnote content is also declared with a label, which must match the label used for the footnote reference. It can be inserted at an arbitrary position in the document and is always rendered at the bottom of the page. Furthermore, a backlink is automatically added to the footnote reference. diff --git a/docs/extensions/pymdown.md b/docs/extensions/pymdown.md index 8c82200f3..e375db2aa 100644 --- a/docs/extensions/pymdown.md +++ b/docs/extensions/pymdown.md @@ -45,7 +45,7 @@ the Markdown experience closer to GitHub Flavored Markdown (GFM). The PyMdown Extensions package adds a shorthand to enable all of the included extensions that provide the GFM experience. However, usage of the shorthand is discouraged, because some extensions are not supported, as the Material theme -uses the counterparts included in the standard Markdown library. +uses some incompatible extensions included in the standard Markdown library. #### BetterEm @@ -132,7 +132,7 @@ Result: [Tilde][13] provides an easy way to ~~strike through~~ cross out text. The portion of text that should be erased must be enclosed in two tildes -`~~...~~`, and the extension will take care of the rest. +`~~...~~` and the extension will take care of the rest. [13]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ @@ -171,13 +171,13 @@ During compilation of the Markdown document, changes can be rendered (default), accepted or rejected. Text can be {--deleted--} and replacement text {++added++}. This can also be -combined in {~~one~>a single~~} operation. {==Highlighting==} is also possible -{>>and comments can be added inline<<}. +combined into {~~one~>a single~~} operation. {==Highlighting==} is also +possible {>>and comments can be added inline<<}. {== -This can also be applied to blocks, by putting the opening and closing tags on -separate lines and adding a new line between the tag and the content each. +Formatting can also be applied to blocks, by putting the opening and closing +tags on separate lines and adding new lines between the tags and the content. ==} @@ -194,7 +194,7 @@ mathematical notation. See [this thread][22] for a short introduction and quick reference on how to write equations in TeX syntax. Besides activating the extension in the `mkdocs.yml`, the MathJax JavaScript -runtime needs to be included. This can be done with +runtime needs to be included. This must be done with [additional JavaScript][23]: ``` yaml @@ -233,7 +233,7 @@ In your `mkdocs.yml`, include it with: ``` yaml extra_javascript: - - 'extra.js' + - 'javascripts/extra.js' - 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML' ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index ed0c6cd0f..1d770d6b9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,7 +4,7 @@ ### Installing MkDocs -Before installing [MkDocs][1], you need to make sure you have Python and `pip` +Before installing [MkDocs][2], you need to make sure you have Python and `pip` – the Python package manager – up and running. You can verify if you're already good to go with the following commands: @@ -26,17 +26,18 @@ pip install mkdocs && mkdocs --version Material requires MkDocs >= 0.16. -Furthermore, it is highly recommended to install [Pygments][2] and the -[PyMdown Extensions][3] to get the most out of the Material theme: +Furthermore, it is highly recommended to install [Pygments][3] and the +[PyMdown Extensions][4] to get the most out of the Material theme: ```sh pip install pygments pip install pymdown-extensions ``` - [1]: http://www.mkdocs.org - [2]: http://pygments.org - [3]: http://facelessuser.github.io/pymdown-extensions/ + [1]: https://hub.docker.com/r/squidfunk/mkdocs-material/ + [2]: http://www.mkdocs.org + [3]: http://pygments.org + [4]: http://facelessuser.github.io/pymdown-extensions/ ### Installing Material @@ -48,11 +49,11 @@ Material can be installed with `pip`: pip install mkdocs-material ``` -!!! warning "Installation on Mac OS X" +!!! warning "Installation on macOS" - When you're running the pre-installed version of Python on OS X, `pip` tries - to install packages in a folder for which your user might not have the - adequate permissions. There are two possible solutions to this: + When you're running the pre-installed version of Python on macOS, `pip` + tries to install packages in a folder for which your user might not have + the adequate permissions. There are two possible solutions to this: 1. **Installing in user space** (recommended): Provide the `--user` flag to the install command and `pip` will install the package in a user-site @@ -60,11 +61,11 @@ pip install mkdocs-material 2. **Switching to a homebrewed Python**: Upgrade your Python installation to a self-contained solution by installing Python with Homebrew. This - will also eliminate any problems you may be having with `pip`. + should eliminate a lot of problems you may be having with `pip`. #### by cloning from GitHub -Material can also be used without system-wide installation by cloning the +Material can also be used without a system-wide installation by cloning the repository into a subfolder of your project's root directory: ``` sh @@ -84,24 +85,24 @@ your `mkdocs.yml`. If you installed Material using pip: theme: 'material' ``` -When you cloned Material from GitHub, use: +If you cloned Material from GitHub: ``` yaml theme_dir: 'mkdocs-material/material' ``` -That's it. MkDocs includes a development server, so you can view your changes -as you go - very handy. Spin it up with the following command: +MkDocs includes a development server, so you can view your changes as you go. +The development server can be started with the following command: ``` sh mkdocs serve ``` -Now you can point your browser to [localhost:8000][4] and the Material theme -should be visible. You can now start writing your documentation, or read on and -customize the theme through some options. +Now you can point your browser to [localhost:8000][5] and the Material theme +should be visible. From here on, you can start writing your documentation, or +read on and customize the theme through some options. - [4]: http://localhost:8000 + [5]: http://localhost:8000 ## Options @@ -111,7 +112,7 @@ project's `mkdocs.yml`. See the following section for all available options. ### Changing the color palette Material defines a default hue for every primary and accent color on Google's -material design [color palette][5]. This makes it very easy to change the +Material Design [color palette][6]. This makes it very easy to change the overall look of the theme. Just set the primary and accent colors using the following variables in your `mkdocs.yml`: @@ -122,19 +123,19 @@ extra: accent: 'light blue' ``` -Color names can be written upper- or lowercase but must match the names of the -material design color palette. Valid values are: `red`, `pink`, `purple`, -`deep purple`, `indigo`, `blue`, `light blue`, `cyan`, `teal`, `green`, `light -green`, `lime`, `yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and -`blue grey`. The last three colors can only be used as a primary color. +Color names are case-insensitive, but must match the names of the Material +Design color palette. Valid values are: `red`, `pink`, `purple`, `deep purple`, +`indigo`, `blue`, `light blue`, `cyan`, `teal`, `green`, `light green`, `lime`, +`yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and `blue grey`. +The last three colors can only be used as a primary color. If the color is set via this configuration, an additional CSS file that defines the color palette is included. If you want to keep things lean, clone -the repository and recompile the theme with your custom colors set. See -[this article][6] for more information. +the repository and recompile the theme with your custom colors set. See the +guide on [customization][7] for more information. - [5]: http://www.materialui.co/colors - [6]: customization.md + [6]: http://www.materialui.co/colors + [7]: customization.md #### Primary colors @@ -201,10 +202,10 @@ Click on a tile to change the accent color of the theme: ### Changing the font family -Material uses the [Roboto font family][7] by default, specifically the regular +Material uses the [Roboto font family][8] by default, specifically the regular sans-serif type for text and the `monospaced` type for code. Both fonts are -loaded from [Google Fonts][8] and can easily be changed to other fonts, like -for example the [Ubuntu font family][9]: +loaded from [Google Fonts][9] and can easily be changed to other fonts, like +for example the [Ubuntu font family][10]: ``` yaml extra: @@ -222,9 +223,9 @@ extra: font: 'none' ``` - [7]: https://fonts.google.com/specimen/Roboto - [8]: https://fonts.google.com/ - [9]: https://fonts.google.com/specimen/Ubuntu + [8]: https://fonts.google.com/specimen/Roboto + [9]: https://fonts.google.com/ + [10]: https://fonts.google.com/specimen/Ubuntu ### Adding a logo @@ -243,9 +244,9 @@ extra: If you want to link your social accounts, the Material theme provides an easy way for doing this in the footer of the documentation using the automatically -included [FontAwesome][10] webfont. The syntax is simple – the `type` denotes -the name of the social service, e.g. `github`, `twitter` or `linkedin` and -the `link`, well, resembles the link: +included [FontAwesome][11] webfont. The syntax is simple – the `type` must +denote the name of the social service, e.g. `github`, `twitter` or `linkedin` +and the `link` must contain the URL you want to link to: ``` yaml extra: @@ -258,11 +259,11 @@ extra: link: 'https://de.linkedin.com/in/martin-donath-20a95039' ``` -The links are generated in order and the type of the link must match the name -of the FontAwesome glyph. The `fa` is automatically added, so `github` will -result in `fa fa-github`. +The links are generated in order and the `type` of the links must match the +name of the FontAwesome glyph. The `fa` is automatically added, so `github` +will result in `fa fa-github`. - [10]: http://fontawesome.io/icons/ + [11]: http://fontawesome.io/icons/ ### Google Analytics integration @@ -295,7 +296,7 @@ inside the macro `t`: ``` Just copy the file from the original theme and make your adjustments. See the -section on [overriding partials][11] in the customization guide. +section on [overriding partials][12] in the customization guide. !!! warning "Migrating from Material 0.2.x" @@ -303,18 +304,18 @@ section on [overriding partials][11] in the customization guide. `mkdocs.yml`. With 1.0.0 this is no longer possible as the configuration will be ignored. - [11]: customization.md#overriding-partials + [12]: customization.md#overriding-partials ### More advanced customization If you want to change the general appearance of the Material theme, see -[this article][12] for more information on advanced customization. +[this article][13] for more information on advanced customization. - [12]: customization.md + [13]: customization.md ## Extensions -MkDocs supports several [Markdown extensions][13]. The following extensions +MkDocs supports several [Markdown extensions][14]. The following extensions are not enabled by default (see the link for which are enabled by default) but highly recommended, so they should be switched on at all times: @@ -328,18 +329,18 @@ markdown_extensions: For more information, see the following list of extensions supported by the Material theme including more information regarding installation and usage: -* [Admonition][14] -* [Codehilite][15] -* [Permalinks][16] -* [Footnotes][17] -* [PyMdown Extensions][18] +* [Admonition][15] +* [Codehilite][16] +* [Permalinks][17] +* [Footnotes][18] +* [PyMdown Extensions][19] - [13]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions - [14]: extensions/admonition.md - [15]: extensions/codehilite.md - [16]: extensions/permalinks.md - [17]: extensions/footnotes.md - [18]: extensions/pymdown.md + [14]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions + [15]: extensions/admonition.md + [16]: extensions/codehilite.md + [17]: extensions/permalinks.md + [18]: extensions/footnotes.md + [19]: extensions/pymdown.md ## Full example diff --git a/docs/index.md b/docs/index.md index b4ac2f8b9..d1cd26423 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,10 @@ # Material for MkDocs -## Build beautiful documentation +## Beautiful project documentation Material is a theme for [MkDocs][1], an excellent static site generator geared towards project documentation. It is built using Google's [Material Design][2] -guidelines, fully responsive and optimized for touch and pointer devices. - -Material is very lightweight – it is built from scratch using Javascript and -CSS that weighs approximately 30kb (minified, gzipped and excluding Google -Fonts and Analytics). Yet, it is highly customizable and degrades gracefully in -older browsers. +guidelines. [1]: http://www.mkdocs.org [2]: https://www.google.com/design/spec/material-design @@ -31,31 +26,3 @@ theme: 'material' For detailed instructions see the [getting started guide][3]. [3]: getting-started.md - -## Features - -* Beautiful, readable and very user-friendly design based on Google's Material - Design guidelines, packed in a full responsive template with a well-defined - and [easily customizable color palette][4], great typography, as well as a - beautiful search interface. - -* Responsive specimen like code blocks, tables that work on all screen sizes, - working with and without JavaScript which makes it gracefully degrade in - older browsers. - -- Extra configuration options like a [project logo][5], links to - [social accounts][6], display of the amount of stars your project has on - GitHub and [Google Analytics integration][7]. - -- Easily [extendable and customizable][8] due to a well-designed asset pipeline - built on-top of modern web technologies and modular and abstracted - style definitions.. - -- Web application capability on iOS – when the page is saved to the homescreen, - it behaves and looks like a native application. - - [4]: getting-started.md#changing-the-color-palette - [5]: getting-started.md#adding-a-logo - [6]: getting-started.md#adding-social-links - [7]: getting-started.md#google-analytics-integration - [8]: customization.md diff --git a/docs/release-notes.md b/docs/release-notes.md index 88adb7959..acd4e23db 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -26,7 +26,7 @@ pip show mkdocs-material | grep -E ^Version * Introduced git-hooks for better development workflow * Rewrite of CSS using the BEM methodology and SassDoc guidelines * Rewrite of JavaScript using ES6 and Babel as a transpiler -* Rewrite of Admonition, Permalinks and Codehilite integration +* Rewrite of Admonition, Permalinks and CodeHilite integration * Rewrite of the complete typographical system * Rewrite of Gulp asset pipeline in ES6 and separation of tasks * Removed Bower as a dependency in favor of NPM diff --git a/mkdocs.yml b/mkdocs.yml index 9c2ea05df..e60f188ad 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,7 +20,7 @@ # Project information site_name: Material for MkDocs -site_description: A material design theme for MkDocs +site_description: A Material Design theme for MkDocs site_author: Martin Donath site_url: http://squidfunk.github.io/mkdocs-material/ @@ -39,9 +39,6 @@ extra: palette: primary: indigo accent: indigo - font: - text: Roboto - mono: Roboto Mono social: - type: github-alt link: https://github.com/squidfunk diff --git a/package.json b/package.json index 9e004c8c5..f5dd37c55 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "mkdocs-material", "version": "1.0.0", - "description": "A material design theme for MkDocs", + "description": "A Material Design theme for MkDocs", "keywords": [ "mkdocs", "documentation", diff --git a/setup.py b/setup.py index a2892d38d..ca6a66f58 100644 --- a/setup.py +++ b/setup.py @@ -26,7 +26,7 @@ setup( version = "1.0.0", url = "http://squidfunk.github.io/mkdocs-material/", license = "MIT", - description = "A material design theme for MkDocs", + description = "A Material Design theme for MkDocs", author = "Martin Donath", author_email = "martin.donath@squidfunk.com", keywords = ["mkdocs", "documentation", "theme"],