From 1e590ba8724618a8879031b68de63f8d74a949d7 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Mon, 2 Jan 2017 23:11:32 +0100 Subject: [PATCH] Updated documentation for 1.0.0 --- docs/contributing.md | 66 ++++++++++ docs/customization.md | 236 +++++++++++++++++++++++++++-------- docs/extensions/footnotes.md | 10 +- docs/extensions/pymdown.md | 2 +- docs/getting-started.md | 6 +- docs/index.md | 14 ++- docs/specimen.md | 99 +++------------ 7 files changed, 283 insertions(+), 150 deletions(-) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..64b79ecd7 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,66 @@ +# Contributing + +Interested in contributing to the Material theme? Before you do, please read +the following guidelines. + +## Submission context + +### Got a question or problem? + +For quick questions there's no need to open an issue as you can reach us on +[gitter.im][1]. + + [1]: https://gitter.im/mkdocs-material/general + +### 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. + +### Missing a feature? + +You can request a new feature by submitting an issue to our GitHub Repository. +If you would like to implement a new feature, please submit an issue with a +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 + 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 + 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. + +## Submission guidelines + +### Submitting an issue + +Before you submit an issue, please search the issue tracker, maybe an issue for +your problem already exists and the discussion might inform you of workarounds +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. + +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. + +### 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. + +After your PR is merged, you can safely delete your branch and pull the changes +from the main (upstream) repository. diff --git a/docs/customization.md b/docs/customization.md index ab927c1a3..60ba2ae10 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -1,100 +1,228 @@ # Customization -## A good starting point +## A great starting point Project documentation is as diverse as the projects themselves and the Material -theme is a good starting point for making it look good. However, as you write +theme is a good starting point for making it look great. However, as you write your documentation, you may reach some point where some small adjustments are necessary to preserve the style. -## Small tweaks +## Adding assets -[MkDocs][] provides a simple way for making small adjustments, that is changing -some margins, centering text, etc. Simply put the CSS and Javascript files that -contain your adjustments in the `docs` directory (ideally in subdirectories of -their own) and include them via the `extra_css` and `extra_javascript` -variables in your `mkdocs.yml`: +[MkDocs][1] provides several ways to interfere with themes. In order to make a +few tweaks to an existing theme, you can just add your stylesheets and +JavaScript files to the `docs` directory. -``` yaml -extra_css: ['/stylesheets/extra.css'] -extra_javascript: ['/javascripts/extra.js'] + [1]: http://www.mkdocs.org + +### Additional stylesheets + +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: + +``` sh +mkdir docs/stylesheets +touch docs/stylesheets/extra.css ``` -Further assistance on including extra CSS and Javascript can be found in the -[MkDocs documentation][]. +Then, add the following line to your `mkdocs.yml`: -## Fundamental changes +``` yaml +extra_css: ['stylesheets/extra.css'] +``` -If you want to make larger adjustments like changing the color palette or -typography, you should check out or download the repository of the project and -compile the SASS sources with your changes. The project design is very modular, -so most things can be tweaked by changing a few variables. +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? -### Setup +### Additional JavaScript -In order to compile the project, you need `node` with a version greater than -`0.11` up and running. +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: -The project itself is hosted on GitHub, so the next -thing you should do is clone the project from GitHub: +``` sh +mkdir docs/javascripts +touch docs/javascripts/extra.js +``` + +Then, add the following line to your `mkdocs.yml`: + +``` yaml +extra_javascript: ['javascripts/extra.js'] +``` + +Further assistance can be found in the [MkDocs documentation][2]. + + [2]: http://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme + +## Extending the theme + +If you want to alter the HTML source (e.g. add or remove some part), you can +extend the theme. From version 0.16 on MkDocs implements [theme extension][3], +an easy way to override parts of a theme without forking and changing the +main theme. + + [3]: http://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme_dir + +### Setup and theme structure + +Reference the Material theme as usual in your `mkdocs.yml`, and create a +new folder for overrides, e.g. `theme`, which you reference using `theme_dir`: + +``` yaml +theme: 'material' +theme_dir: 'theme' +``` + +!!! warning "Theme extension prerequisites" + + As the `theme_dir` variable is used for the theme extension process, the + Material theme needs to be installed via `pip` and referenced with the + `theme` parameter in your `mkdocs.yml`. + +The structure in the theme directory must mirror the directory structure of the +original theme, as any file in the theme directory will replace the file with +the same name which is part of the original theme. Besides, further assets +may also be put in the theme directory. + +The directory layout of the Material theme is as follows: + +``` sh +. +├─ assets/ +│ ├─ images/ # Images and icons +│ ├─ javascripts/ # JavaScript +│ └─ stylesheets/ # Stylesheets +├─ partials/ +│ ├─ fonts.html # Webfont definitions +│ ├─ footer.html # Footer bar +│ ├─ header.html # Header bar +│ ├─ nav-item.html # Main navigation item +│ ├─ nav.html # Main navigation +│ ├─ search.html # Search box +│ ├─ source.html # Repository information +│ ├─ svgs.html # Inline SVG definitions +│ ├─ toc-item.html # Table of contents item +│ └─ toc.html # Table of contents +├─ 404.html # 404 error page +├─ base.html # Base template +└─ main.html # Default page +``` + +### Overriding partials + +In order to override the footer, we can replace the `footer.html` partial with +our own partial. To do this, create the file `partials/footer.html` in the +theme directory. MkDocs will now use the new partial when rendering the theme. +This can be done with any file. + +### Overriding template blocks + +Besides overriding partials, one can also override so called template blocks, +which are defined inside the Material theme and wrap specific features. To +override a template block, create a `main.html` inside the theme directory and +define the block, e.g.: + +``` jinja +{% extends "base.html" %} + +{% block htmltitle %} + Lorem ipsum dolor sit amet +{% endblock %} +``` + +The Material theme provides the following template blocks: + +| Block name | Wrapped contents | +| ------------ | ----------------------------------------------- | +| `analytics` | Wraps the Google Analytics integration | +| `content` | Wraps the main content | +| `extrahead` | Empty block to define additional meta tags | +| `fonts` | Wraps the webfont definitions | +| `footer` | Wraps the footer with navigation and copyright | +| `header` | Wraps the fixed header bar | +| `htmltitle` | Wraps the `` tag | +| `libs` | Wraps the JavaScript libraries, e.g. Modernizr | +| `repo` | Wraps the repository link in the header bar | +| `scripts` | Wraps the JavaScript application logic | +| `search_box` | Wraps the search form in the header bar | +| `site_meta` | Wraps the meta tags in the document head | +| `site_name` | Wraps the site name in the header bar | +| `site_nav` | Wraps the site navigation and table of contents | +| `styles` | Wraps the stylesheets (also extra sources) | + +For more on this topic refer to the [MkDocs documentation][4] + + [4]: http://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks + +## Theme development + +The Material theme is built on modern technologies like ES6, [Webpack][5], +[Babel][6] and [SASS][7]. If you want to make more fundamental changes, it may +be necessary to make the adjustments directly in the source of the Material +theme and recompile it. This is fairly easy. + + [5]: https://webpack.github.io/ + [6]: https://babeljs.io + [7]: http://sass-lang.com + +### Environment setup + +In order to start development on the Material theme, a [Node.js][8] version of +at least 4 is required. Clone the repository from GitHub: ``` sh git clone https://github.com/squidfunk/mkdocs-material ``` -Then you change the directory and install all dependencies specified in the -`package.json` and `bower.json` with the following command: +Next, all dependencies need to be installed, which is done with: ``` sh cd mkdocs-material npm install ``` -### Development + [8]: https://nodejs.org -The asset pipeline is contained in `Gulpfile.js`, which you can start with -`gulp watch`. If you specify the `--mkdocs` flag, this will also run -`mkdocs serve`, to monitor changes to the documentation. Point your browser to [localhost:8000](http://localhost:8000) and you should see this very -documentation in front of your eyes. +### Development mode + +The Material theme uses a sophisticated asset pipeline using [Gulp][9] and +Webpack which can be started with the following command: ``` sh -gulp watch --mkdocs +npm run start ``` -For example, changing the color palette is as simple as changing the `$primary` -and `$accent` variables in `src/assets/stylesheets/_palette.scss`: +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. + +For example, changing the color palette is as simple as changing the +`$md-color-primary` and `$md-color-accent` variables in +`src/assets/stylesheets/_config.scss`: ``` css -$primary: $red-400; -$accent: $teal-a700; +$md-color-primary: $clr-red-400; +$md-color-accent: $clr-teal-a700; ``` -The color variables are defined by the SASS library [quantum-colors][] and -resemble all the colors contained in the material design palette. -[This page][material-colors] offers a really good overview of the palette. + [9]: http://gulpjs.com -### Building +### Build process When you finished making your changes, you can build the theme by invoking: ``` sh -gulp build --production +npm run build ``` -The `--production` flag triggers the production-level compilation and -minification of all CSS and Javascript sources. When the command is ready, -the final theme is located in the `material` directory. Add the `theme_dir` -variable pointing to the aforementioned directory in your original -`mkdocs.yml`: - -``` yaml -theme_dir: 'mkdocs-material/material' -``` +This triggers the production-level compilation and minification of all +stylesheets and JavaScript sources. When the command is ready, the final +theme is located in the `material` directory. Add the `theme_dir` variable +pointing to the aforementioned directory in your original `mkdocs.yml`. Now you can run `mkdocs build` and you should see your documentation with your changes to the original Material theme. - -[MkDocs]: http://www.mkdocs.org -[MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme -[quantum-colors]: https://github.com/nkpfstr/quantum-colors -[material-colors]: http://www.materialui.co/colors diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md index 9967d526f..7f080547d 100644 --- a/docs/extensions/footnotes.md +++ b/docs/extensions/footnotes.md @@ -58,7 +58,7 @@ Result: <a href="#fn:1">Jump to footnote at the bottom of the page</a> -[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. + [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. #### on multiple lines @@ -76,9 +76,9 @@ Example: Result: -[^2]: - 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. + [^2]: + 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. <a href="#fn:2">Jump to footnote at the bottom of the page</a> diff --git a/docs/extensions/pymdown.md b/docs/extensions/pymdown.md index 13a7aeab0..b835f6e44 100644 --- a/docs/extensions/pymdown.md +++ b/docs/extensions/pymdown.md @@ -41,7 +41,7 @@ markdown_extensions: - pymdownx.arithmatex ``` -## Extensions +## Usage ### GitHub Flavored Markdown diff --git a/docs/getting-started.md b/docs/getting-started.md index c382938c0..dbe862ec5 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 @@ -241,7 +241,7 @@ 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 [Socicon][8] 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: +`link`, well, resembles the link: ``` yaml extra: diff --git a/docs/index.md b/docs/index.md index 1ac5b1ae2..a71195f7c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,9 @@ # Material <small>for MkDocs</small> -## Beautiful documentation +## Build beautiful documentation -Material is a theme for [MkDocs][], an excellent static site generator geared -towards project documentation. It is built using Google's [material design][] +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, full responsive, optimized for touch and pointer devices as well as all sorts of screen sizes. @@ -12,9 +12,12 @@ CSS that weighs less than 30kb (minified, gzipped and excluding Google Fonts and Analytics). Yet, it is highly customizable and degrades gracefully in older browsers. + [1]: http://www.mkdocs.org + [2]: https://www.google.com/design/spec/material-design + ## Quick start -Install with `pip`: +Install the latest version of Material with `pip`: ``` sh pip install mkdocs-material @@ -52,8 +55,7 @@ theme: 'material' See the [getting started guide](getting-started.md) for instructions how to get it up and running. -[MkDocs]: http://www.mkdocs.org -[material design]: https://www.google.com/design/spec/material-design + [checkbox hack]: http://tutorialzine.com/2015/08/quick-tip-css-only-dropdowns-with-the-checkbox-hack/ [project logo]: getting-started.md#adding-a-logo [easily customizable color palette]: getting-started.md#changing-the-color-palette diff --git a/docs/specimen.md b/docs/specimen.md index 9dad11f0b..fefccdea0 100644 --- a/docs/specimen.md +++ b/docs/specimen.md @@ -1,8 +1,6 @@ # Specimen -## Typography - -### Body copy +## Body copy Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras arcu libero, mollis sed massa vel, *ornare viverra ex*. Mauris a ullamcorper lacus. Nullam @@ -16,7 +14,9 @@ eros. [Nulla aliquam](/) orci sit amet nisl posuere malesuada. Proin aliquet nulla velit, quis ultricies orci feugiat et. `Ut tincidunt sollicitudin` tincidunt. Aenean ullamcorper sit amet nulla at interdum. -### Headings +## Headings + +### The 3rd level #### The 4th level @@ -24,7 +24,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. ###### The 6th level -### Headings <small>with secondary text</small> +## Headings <small>with secondary text</small> + +### The 3rd level <small>with secondary text</small> #### The 4th level <small>with secondary text</small> @@ -32,7 +34,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. ###### The 6th level <small>with secondary text</small> -### Blockquotes +## Blockquotes > Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc @@ -40,7 +42,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie imperdiet consectetur. -#### Blockquote nesting +### Blockquote nesting > **Sed aliquet**, neque at rutrum mollis, neque nisi tincidunt nibh, vitae faucibus lacus nunc at lacus. Nunc scelerisque, quam id cursus sodales, lorem @@ -55,7 +57,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. Interdum et malesuada fames ac ante ipsum primis in faucibus. Sed nec leo bibendum, sodales mauris ut, tincidunt massa. -#### Other content blocks +### Other content blocks > Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl, @@ -76,9 +78,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. vel lacinia lacus. Suspendisse rhoncus nunc non nisi iaculis ultrices. Donec consectetur mauris non neque imperdiet, eget volutpat libero. -### Lists +## Lists -#### Unordered lists +### Unordered lists * Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci, @@ -96,7 +98,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh lacinia sed. Aenean in finibus diam. -#### Ordered lists +### Ordered lists 1. Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla @@ -135,9 +137,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum. sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo. -### Code blocks +## Code blocks -#### Inline +### Inline Morbi eget `dapibus felis`. Vivamus *`venenatis porttitor`* tortor sit amet rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra, @@ -148,7 +150,7 @@ Nam vehicula nunc `:::js return target` mauris, a ultricies libero efficitur sed. Sed molestie imperdiet consectetur. Vivamus a pharetra leo. Pellentesque eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus. -#### Listing +### Listing #!js hl_lines="8" var _extends = function(target) { @@ -161,7 +163,7 @@ eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus. return target; }; -### Horizontal rules +## Horizontal rules Aenean in finibus diam. Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna @@ -173,7 +175,7 @@ Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla consectetur feugiat sodales. -### Data tables +## Data tables | Sollicitudo / Pellentesi | consectetur | adipiscing | elit | arcu | sed | | ------------------------ | ----------- | ---------- | ------- | ---- | --- | @@ -224,68 +226,3 @@ sit amet laoreet nibh. </tr> </tbody> </table> - -## Colors - -### Primary colors - -Click on a tile to change the primary color of the theme: - -<button data-md-color-primary="red">Red</button> -<button data-md-color-primary="pink">Pink</button> -<button data-md-color-primary="purple">Purple</button> -<button data-md-color-primary="deep-purple">Deep Purple</button> -<button data-md-color-primary="indigo">Indigo</button> -<button data-md-color-primary="blue">Blue</button> -<button data-md-color-primary="light-blue">Light Blue</button> -<button data-md-color-primary="cyan">Cyan</button> -<button data-md-color-primary="teal">Teal</button> -<button data-md-color-primary="green">Green</button> -<button data-md-color-primary="light-green">Light Green</button> -<button data-md-color-primary="lime">Lime</button> -<button data-md-color-primary="yellow">Yellow</button> -<button data-md-color-primary="amber">Amber</button> -<button data-md-color-primary="orange">Orange</button> -<button data-md-color-primary="deep-orange">Deep Orange</button> -<button data-md-color-primary="brown">Brown</button> -<button data-md-color-primary="grey">Grey</button> -<button data-md-color-primary="blue-grey">Blue Grey</button> - -<script> - var buttons = document.querySelectorAll("button[data-md-color-primary]"); - Array.prototype.forEach.call(buttons, function(button) { - button.addEventListener("click", function() { - document.body.dataset.mdColorPrimary = this.dataset.mdColorPrimary; - }) - }) -</script> - -### Accent colors - -Click on a tile to change the accent color of the theme: - -<button data-md-color-accent="red">Red</button> -<button data-md-color-accent="pink">Pink</button> -<button data-md-color-accent="purple">Purple</button> -<button data-md-color-accent="deep-purple">Deep Purple</button> -<button data-md-color-accent="indigo">Indigo</button> -<button data-md-color-accent="blue">Blue</button> -<button data-md-color-accent="light-blue">Light Blue</button> -<button data-md-color-accent="cyan">Cyan</button> -<button data-md-color-accent="teal">Teal</button> -<button data-md-color-accent="green">Green</button> -<button data-md-color-accent="light-green">Light Green</button> -<button data-md-color-accent="lime">Lime</button> -<button data-md-color-accent="yellow">Yellow</button> -<button data-md-color-accent="amber">Amber</button> -<button data-md-color-accent="orange">Orange</button> -<button data-md-color-accent="deep-orange">Deep Orange</button> - -<script> - var buttons = document.querySelectorAll("button[data-md-color-accent]"); - Array.prototype.forEach.call(buttons, function(button) { - button.addEventListener("click", function() { - document.body.dataset.mdColorAccent = this.dataset.mdColorAccent; - }) - }) -</script>