From efff866b62b823d6ce6b50d878e17a11632f8b4d Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 7 Jan 2017 20:07:41 +0100 Subject: [PATCH] Added documentation on contribution + some formatting --- docs/contributing.md | 39 +++++++++++----- docs/customization.md | 16 +++++-- docs/extensions/admonition.md | 24 ++++++---- docs/extensions/pymdown.md | 43 ++++++++---------- docs/getting-started.md | 86 +++++++++++++++++++++-------------- docs/license.md | 4 +- 6 files changed, 127 insertions(+), 85 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 64b79ecd7..8c3bcf7fa 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,7 +1,7 @@ # Contributing -Interested in contributing to the Material theme? Before you do, please read -the following guidelines. +Interested in contributing to the Material theme? Want to report a bug? Before +you do, please read the following guidelines. ## Submission context @@ -15,8 +15,12 @@ For quick questions there's no need to open an issue as you can reach us on ### Found a bug? If you found a bug in the source code, you can help us by submitting an issue -to our GitHub Repository. Even better, you can submit a Pull Request with a -fix. However, before doing so, read the submission guidelines. +to the [issue tracker][2] in our GitHub repository. Even better, you can submit +a Pull Request with a fix. However, before doing so, please read the +[submission guidelines][3]. + + [2]: https://github.com/squidfunk/mkdocs-material/issues + [3]: #submission-guidelines ### Missing a feature? @@ -47,20 +51,31 @@ readily available. We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. In order to reproduce bugs we will systematically ask you to provide a minimal reproduction scenario using the -custom issue template. +custom issue template. Please stick to the issue template. Unfortunately we are not able to investigate / fix bugs without a minimal -reproduction, so if we don't hear back from you we are going to close issues -that don't have enough information to be reproduced. +reproduction scenario, so if we don't hear back from you we may close the issue. ### Submitting a Pull Request (PR) Search GitHub for an open or closed PR that relates to your submission. You -don't want to duplicate effort. Fork the project, make your changes in **a new -git branch** and commit your changes with a descriptive commit message. Then -push your branch to GitHub and send a PR to `mkdocs-material:master`. If we -suggest changes, make the required updates, rebase your branch and push -the changes to your GitHub repository, which will automatiaclly update your PR. +don't want to duplicate effort. If you do not find a related issue or PR, +go ahead. + +1. **Development**: Fork the project, set up the [development environment][4], + make your changes in a separate git branch and add descriptive messages to + your commits. + +2. **Build**: Before submitting a pull requests, build the theme. This is a + mandatory requirement for your PR to get accepted, as the theme should at + all times be installable through GitHub. + +3. **Pull Request**: After building the theme, commit the compiled output, push + your branch to GitHub and send a PR to `mkdocs-material:master`. If we + suggest changes, make the required updates, rebase your branch and push the + changes to your GitHub repository, which will automatically update your PR. After your PR is merged, you can safely delete your branch and pull the changes from the main (upstream) repository. + + [4]: http://localhost:8000/customization/#theme-development diff --git a/docs/customization.md b/docs/customization.md index 1735c6920..a8b7cb36c 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -19,7 +19,7 @@ JavaScript files to the `docs` directory. If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate stylesheet. The easiest way is by creating a -new stylesheet file in your docs directory: +new stylesheet file in your `docs` directory: ``` sh mkdir docs/stylesheets @@ -40,7 +40,7 @@ saving, as the MkDocs development server implements live reloading. Cool, huh? The same is true for additional JavaScript. If you want to integrate another syntax highlighter or add some custom logic to your theme, create a new -JavaScript file in your docs directory: +JavaScript file in your `docs` directory: ``` sh mkdir docs/javascripts @@ -99,6 +99,7 @@ The directory layout of the Material theme is as follows: │ ├─ fonts.html # Webfont definitions │ ├─ footer.html # Footer bar │ ├─ header.html # Header bar +│ ├─ i18n.html # Localized labels │ ├─ nav-item.html # Main navigation item │ ├─ nav.html # Main navigation │ ├─ search.html # Search box @@ -183,6 +184,7 @@ Next, all dependencies need to be installed, which is done with: ``` sh cd mkdocs-material +pip install -r requirements.txt npm install ``` @@ -199,8 +201,7 @@ npm run start This will also start the MkDocs development server which will monitor changes on assets, templates and documentation. Point your browser to -[localhost:8000](http://localhost:8000) and you should see this very -documentation in front of your eyes. +[localhost:8000][10] and you should see this documentation in front of you. For example, changing the color palette is as simple as changing the `$md-color-primary` and `$md-color-accent` variables in @@ -211,7 +212,14 @@ $md-color-primary: $clr-red-400; $md-color-accent: $clr-teal-a700; ``` +!!! warning "Automatically generated files" + + Never make any changes in the `material` directory, as the contents of this + directory are automatically generated from the `src` directory and will be + overriden when the theme is built. + [9]: http://gulpjs.com + [10]: http://localhost:8000 ### Build process diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md index 65c71dc34..4a678734e 100644 --- a/docs/extensions/admonition.md +++ b/docs/extensions/admonition.md @@ -18,8 +18,8 @@ markdown_extensions: ## Usage Admonition blocks follow a simple syntax: every block is started with `!!!`, -followed by a single keyword which is used as the [type qualifier](#types) of -the block. The content of the block then follows on the next line, indented by +followed by a single keyword which is used as the [type qualifier][2] of the +block. The content of the block then follows on the next line, indented by four spaces. Example: @@ -38,6 +38,8 @@ Result: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. + [2]: #types + ### Changing the title By default, the block title will equal the type qualifier. However, it can @@ -61,8 +63,8 @@ Result: ### Removing the title -Similar to setting a [custom title](#changing-the-title), the icon and title -can be omitted by providing an empty string after the type qualifier: +Similar to setting a [custom title][3], the icon and title can be omitted by +providing an empty string after the type qualifier: Example: @@ -80,18 +82,20 @@ Result: nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. + [3]: #changing-the-title + ### Embedded code blocks Blocks can contain all kinds of text content, including headlines, lists, paragraphs and other blocks – except code blocks, because the parser from the standard Markdown library does not account for those. -However, the [PyMdown Extensions][2] package adds an extension called -[SuperFences][3], which makes it possible to nest code blocks within other +However, the [PyMdown Extensions][4] package adds an extension called +[SuperFences][5], which makes it possible to nest code blocks within other blocks. - [2]: https://facelessuser.github.io/pymdown-extensions - [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ + [4]: https://facelessuser.github.io/pymdown-extensions + [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ Example: @@ -125,7 +129,9 @@ Example: Admonition supports user-defined type qualifiers which may influence the style of the inserted block. Following is a list of type qualifiers supported by the Material theme, whereas the default type, and thus fallback for unknown type -qualifiers, is [note](#note). +qualifiers, is [note][6]. + + [6]: #note ### Note diff --git a/docs/extensions/pymdown.md b/docs/extensions/pymdown.md index ce8e4143b..9309217a2 100644 --- a/docs/extensions/pymdown.md +++ b/docs/extensions/pymdown.md @@ -15,8 +15,8 @@ The PyMdown Extensions package can be installed with the following command: pip install pymdown-extensions ``` -The following list of extensions that are part of the PyMdown Extensions package -are recommended to be used together with the Material theme: +The following list of extensions that are part of the PyMdown Extensions +package are recommended to be used together with the Material theme: ``` yaml markdown_extensions: @@ -33,14 +33,6 @@ markdown_extensions: - pymdownx.tilde ``` -Additionally, there is a [MathJax integration](#arithmatex) which should only -be switched on if needed, as it adds a few hundred kb of JavaScript: - -``` yaml -markdown_extensions: - - pymdownx.arithmatex -``` - ## Usage ### GitHub Flavored Markdown @@ -138,31 +130,32 @@ The portion of text that should be erased must be enclosed in two tildes #### Caret -[Caret][11] is the sister extension of [Tilde](#tilde) and makes it possible to +[Caret][11] is the sister extension of [Tilde][12] and makes it possible to highlight ^^inserted text^^. The portion of text that should be marked as added must be enclosed in two carets `^^...^^`. [11]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/ + [12]: #tilde #### Mark -[Mark][12] adds the ability to ==highlight text== like it was marked with a +[Mark][13] adds the ability to ==highlight text== like it was marked with a ==yellow text marker==. The portion of text that should be highlighted must be enclosed in two equal signs `==...==`. - [12]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ + [13]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ #### SmartSymbols -[SmartSymbols][13] converts markup for special characters into their +[SmartSymbols][14] converts markup for special characters into their corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...). - [13]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ + [14]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ #### Critic -[Critic][14] implements [Critic Markup][15], a Markdown extension that enables +[Critic][15] implements [Critic Markup][16], a Markdown extension that enables the tracking of changes (additions, deletions and comments) on documents. During compilation of the Markdown document, changes can be rendered (default), accepted or rejected. @@ -171,21 +164,21 @@ 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<<}. - [14]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/ - [15]: http://criticmarkup.com/ + [15]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/ + [16]: http://criticmarkup.com/ ### Math and code highlighting #### Arithmatex -[Arithmatex][16] integrates Material with [MathJax][17] which parses +[Arithmatex][17] integrates Material with [MathJax][18] which parses block-style and inline equations written in TeX markup and outputs them in -mathematical notation. See [this thread][18] for a short introduction and quick +mathematical notation. See [this thread][19] for a short introduction and quick reference on how to write equations in TeX syntax. - [16]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ - [17]: https://www.mathjax.org/ - [18]: http://meta.math.stackexchange.com/questions/5020/ + [17]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ + [18]: https://www.mathjax.org/ + [19]: http://meta.math.stackexchange.com/questions/5020/ ##### Blocks @@ -221,9 +214,9 @@ Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$ #### Inlinehilite -[Inlinehilite][19] adds support for inline code highlighting. It's useful for +[Inlinehilite][20] adds support for inline code highlighting. It's useful for short snippets included within body copy, e.g. `#!js var test = 0;` and can be achived by prefixing inline code with a shebang and language identifier, e.g. `#!js`. - [19]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ + [20]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ diff --git a/docs/getting-started.md b/docs/getting-started.md index aad71ce53..fbcf041d1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -26,8 +26,8 @@ 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][2] and the +[PyMdown Extensions][3] to get the most out of the Material theme: ```sh pip install pygments @@ -71,8 +71,9 @@ repository into a subfolder of your project's root directory: git clone https://github.com/squidfunk/mkdocs-material.git ``` -This is especially useful if you want to extend the theme and use partials. -The theme will reside in the folder `mkdocs-material/material`. +This is especially useful if you want to extend the theme and override some +parts of the theme. The theme will reside in the folder +`mkdocs-material/material`. ## Usage @@ -96,9 +97,11 @@ as you go - very handy. Spin it up with the following command: mkdocs serve ``` -Now you can point your browser to [localhost:8000](http://localhost:8000) 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][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. + + [4]: http://localhost:8000 ## Options @@ -108,7 +111,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][4]. This makes it very easy to change the +material design [color palette][5]. 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`: @@ -127,10 +130,11 @@ green`, `lime`, `yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and 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](customization.md) for more information. +the repository and recompile the theme with your custom colors set. See +[this article][6] for more information. - [4]: http://www.materialui.co/colors + [5]: http://www.materialui.co/colors + [6]: customization.md #### Primary colors @@ -197,10 +201,10 @@ Click on a tile to change the accent color of the theme: ### Changing the font family -Material uses the [Roboto font family][5] by default, specifically the regular -sans-serif type for text and the monospaced type for code. Both fonts are -loaded from [Google Fonts][6] and can easily be changed to other fonts, like -for example the [Ubuntu font family][7]: +Material uses the [Roboto font family][7] 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]: ``` yaml extra: @@ -209,7 +213,7 @@ extra: code: 'Ubuntu Mono' ``` -The text font will be loaded in font-weights 400 and **700**, the monospaced +The text font will be loaded in font-weights 400 and **700**, the `monospaced` font in regular weight. If you want to load fonts from other destinations or don't want to use the Google Fonts loading magic, just set `font` to `'none'`: @@ -218,9 +222,9 @@ extra: font: 'none' ``` - [5]: https://fonts.google.com/specimen/Roboto - [6]: https://fonts.google.com/ - [7]: https://fonts.google.com/specimen/Ubuntu + [7]: https://fonts.google.com/specimen/Roboto + [8]: https://fonts.google.com/ + [9]: https://fonts.google.com/specimen/Ubuntu ### Adding a logo @@ -239,7 +243,7 @@ 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][8] webfont. The syntax is simple – the `type` denotes +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: @@ -258,7 +262,7 @@ 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`. - [8]: http://fontawesome.io/icons/ + [10]: http://fontawesome.io/icons/ ### Google Analytics integration @@ -291,19 +295,22 @@ inside the macro `t`: ``` Just copy the file from the original theme and make your adjustments. See the -section on [overriding partials](customization.md/#overriding-partials) in the -customization guide. +section on [overriding partials][11] in the customization guide. + + [11]: customization.md#overriding-partials ### More advanced customization If you want to change the general appearance of the Material theme, see -[this article](customization.md) for more information on advanced customization. +[this article][12] for more information on advanced customization. + + [12]: customization.md ## Extensions -MkDocs supports several [Markdown extensions][9]. 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: +MkDocs supports several [Markdown extensions][13]. 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: ``` yaml markdown_extensions: @@ -312,16 +319,29 @@ markdown_extensions: - toc(permalink=true) ``` +!!! warning "Migrating from Material 0.2.x" + + The [CodeHilite][14] extension was included with + `codehilite(css_class=code)` which switched the CSS class from + `.codehilite` to `.code`. The current version of the theme doesn't require + that and defines styles for the default `.codehilite` class, so the part + `css_class=code` needs to be removed. + For more information, see the following list of extensions supported by the Material theme including more information regarding installation and usage: -* [Admonition](extensions/admonition.md) -* [Codehilite](extensions/codehilite.md) -* [Permalinks](extensions/permalinks.md) -* [Footnotes](extensions/footnotes.md) -* [PyMdown Extensions](extensions/pymdown.md) +* [Admonition][15] +* [Codehilite][14] +* [Permalinks][16] +* [Footnotes][17] +* [PyMdown Extensions][18] - [9]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions + [13]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions + [14]: extensions/codehilite.md + [15]: extensions/admonition.md + [16]: extensions/permalinks.md + [17]: extensions/footnotes.md + [18]: extensions/pymdown.md ## Full example diff --git a/docs/license.md b/docs/license.md index 27d4332be..569a9b93d 100644 --- a/docs/license.md +++ b/docs/license.md @@ -2,7 +2,7 @@ **MIT License** -Copyright (c) 2016 Martin Donath +Copyright © 2016 Martin Donath Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to @@ -20,4 +20,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS -IN THE SOFTWARE. \ No newline at end of file +IN THE SOFTWARE.