diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md index ec8390c8..4514451f 100644 --- a/docs/user-guide/writing-your-docs.md +++ b/docs/user-guide/writing-your-docs.md @@ -1,67 +1,16 @@ # Writing your docs -How to write and layout your markdown source files. +How to layout and write your Markdown source files. --- -## Configure Pages and Navigation - -The [pages configuration](/user-guide/configuration.md#pages) in your -`mkdocs.yml` defines which pages are built by MkDocs and how they appear in the -documentation navigation. If not provided, the pages configuration will be -automatically created by discovering all the Markdown files in the -[documentation directory](/user-guide/configuration.md#docs_dir). An -automatically created pages configuration will always be sorted -alphanumerically by file name. You will need to manually define your pages -configuration if you would like your pages sorted differently. - -A simple pages configuration looks like this: - -```no-highlight -pages: -- 'index.md' -- 'about.md' -``` - -With this example we will build two pages at the top level and they will -automatically have their titles inferred from the filename. Assuming `docs_dir` -has the default value, `docs`, the source files for this documentation would be -`docs/index.md` and `docs/about.md`. To provide a custom name for these pages, -they can be added before the filename. - -```no-highlight -pages: -- Home: 'index.md' -- About: 'about.md' -``` - -### Multilevel documentation - -Subsections can be created by listing related pages together under a section -title. For example: - -```no-highlight -pages: -- Home: 'index.md' -- User Guide: - - 'Writing your docs': 'user-guide/writing-your-docs.md' - - 'Styling your docs': 'user-guide/styling-your-docs.md' -- About: - - 'License': 'about/license.md' - - 'Release Notes': 'about/release-notes.md' -``` - -With the above configuration we have three top level sections: Home, User Guide -and About. Then under User Guide we have two pages, Writing your docs and -Styling your docs. Under the About section we also have two pages, License and -Release Notes. - ## File layout -Your documentation source should be written as regular Markdown files, and -placed in a directory somewhere in your project. Normally this directory will be -named `docs` and will exist at the top level of your project, alongside the -`mkdocs.yml` configuration file. +Your documentation source should be written as regular Markdown files (see +[Writing with Markdown](#writing-with-markdown) below), and placed in the +[documentation directory](configuration.md#docs_dir). By default, this directory +will be named `docs` and will exist at the top level of your project, alongside +the `mkdocs.yml` configuration file. The simplest project you can create will look something like this: @@ -75,7 +24,7 @@ By convention your project homepage should always be named `index`. Any of the following extensions may be used for your Markdown source files: `markdown`, `mdown`, `mkdn`, `mkd`, `md`. -You can also create multi-page documentation, by creating several markdown +You can also create multi-page documentation, by creating several Markdown files: ```no-highlight @@ -116,47 +65,193 @@ nested URLs, like so: /license/ ``` -## Linking documents +### Configure Pages and Navigation + +The [pages configuration](configuration.md#pages) in your `mkdocs.yml` defines +which pages are built by MkDocs and how they appear in the documentation +navigation. If not provided, the pages configuration will be automatically +created by discovering all the Markdown files in the [documentation +directory](configuration.md#docs_dir). An automatically created pages +configuration will always be sorted alphanumerically by file name. You will need +to manually define your pages configuration if you would like your pages sorted +differently. + +A simple pages configuration looks like this: + +```no-highlight +pages: +- 'index.md' +- 'about.md' +``` + +With this example we will build two pages at the top level and they will +automatically have their titles inferred from the filename. Assuming `docs_dir` +has the default value, `docs`, the source files for this documentation would be +`docs/index.md` and `docs/about.md`. To provide a custom name for these pages, +they can be added before the filename. + +```no-highlight +pages: +- Home: 'index.md' +- About: 'about.md' +``` + +Subsections can be created by listing related pages together under a section +title. For example: + +```no-highlight +pages: +- Home: 'index.md' +- User Guide: + - 'Writing your docs': 'user-guide/writing-your-docs.md' + - 'Styling your docs': 'user-guide/styling-your-docs.md' +- About: + - 'License': 'about/license.md' + - 'Release Notes': 'about/release-notes.md' +``` + +With the above configuration we have three top level sections: Home, User Guide +and About. Then under User Guide we have two pages, Writing your docs and +Styling your docs. Under the About section we also have two pages, License and +Release Notes. + +Note that a section cannot have a page assigned to it. Sections are only +containers for child pages and sub-sections. You may nest sections as deeply as +you like. However, be careful that you don't make it too difficult for your +users to navigate through the site navigation by over-complicating the nesting. +While sections may mirror your directly structure, they do not have to. + +## Writing with Markdown + +MkDocs pages must be authored in [Markdown][md], a lightweight markup language +which results in easy-to-read, easy-to-write plain text documents that can be +converted to valid HTML documents in a predictable manner. + +MkDocs uses the [Python-Markdown] library to render Markdown documents to HTML. +Python-Markdown is almost completely compliant with the [reference +implementation][md], although there are a few very minor [differences]. + +In addition to the base Markdown [syntax] which is common across all Markdown +implementations, MkDocs includes support for extending the Markdown syntax with +Python-Markdown [extensions]. See the MkDocs' [markdown_extensions] +configuration setting for details on how to enable extensions. + +MkDocs includes some extensions by default, which are highlighted below. + +[Python-Markdown]: https://python-markdown.github.io/ +[md]: http://daringfireball.net/projects/markdown/ +[differences]: https://python-markdown.github.io/#differences +[syntax]: https://daringfireball.net/projects/markdown/syntax +[extensions]: https://python-markdown.github.io/extensions/ +[markdown_extensions]: configuration.md#markdown_extensions + +### Internal links MkDocs allows you to interlink your documentation by using regular Markdown -hyperlinks. +[links]. However, there are a few additional benefits to formatting those links +specifically for MkDocs as outlines below. -### Internal hyperlinks +[links]: https://daringfireball.net/projects/markdown/syntax#link + +#### Linking to pages When linking between pages in the documentation you can simply use the regular -Markdown hyperlinking syntax, including the relative path to the Markdown +Markdown [linking][links] syntax, including the *relative path* to the Markdown document you wish to link to. - Please see the [project license](license.md) for further details. +```no-highlight +Please see the [project license](license.md) for further details. +``` -When the MkDocs build runs, these hyperlinks will automatically be transformed -into a hyperlink to the appropriate HTML page. - -When working on your documentation you should be able to open the linked -Markdown document in a new editor window simply by clicking on the link. +When the MkDocs build runs, these Markdown links will automatically be +transformed into an HTML hyperlink to the appropriate HTML page. If the target documentation file is in another directory you'll need to make -sure to include any relative directory path in the hyperlink. +sure to include any relative directory path in the link. - Please see the [project license](../about/license.md) for further details. +```no-highlight +Please see the [project license](../about/license.md) for further details. +``` -You can also link to a section within a target documentation page by using an -anchor link. The generated HTML will correctly transform the path portion of the -hyperlink, and leave the anchor portion intact. +The [toc] extension is used by MkDocs to generate an ID for every header in your +Markdown documents. You can use that ID to link to a section within a target +document by using an anchor link. The generated HTML will correctly transform +the path portion of the link, and leave the anchor portion intact. - Please see the [project license](about.md#license) for further details. +```no-highlight +Please see the [project license](about.md#license) for further details. +``` -## Images and media +Note that IDs are created from the text of a header. All text is converted to +lowercase and any disallowed characters, including white-space, are converted to +dashes. Consecutive dashes are then reduced to a single dash. + +There are a few configuration settings provided by the toc extension which you +can set in your `mkdocs.yml` configuration file to alter the default behavior: + +`permalink`: + +: Generate permanent links at the end of each header. Default: `False`. + + When set to True the paragraph symbol (¶ or `¶`) is used as the + link text. When set to a string, the provided string is used as the link + text. For example, to use the hash symbol (`#`) instead, do: + + markdown_extensions: + - toc: + permalink: "#" + +`baselevel`: + +: Base level for headers. Default: `1`. + + This setting allows the header levels to be automatically adjusted to fit + within the hierarchy of your HTML templates. For example, if the Markdown + text for a page should not contain any headers higher than level 2 (`

`), + do: + + markdown_extensions: + - toc: + baselevel: 2 + + Then any headers in your document would be increased by 1. For example, the + header `# Header` would be rendered as a level 2 header (`

`) in the HTML + output. + +`separator`: + +: Word separator. Default: `-`. + + Character which replaces white-space in generated IDs. If you prefer + underscores, then do: + + markdown_extensions: + - toc: + separator: "_" + +Note that if you would like to define multiple of the above settings, you must +do so under a single `toc` entry in the `markdown_extensions` configuration +option. + +```yml +markdown_extensions: + - toc: + permalink: "#" + baselevel: 2 + separator: "_" +``` + +[toc]: https://python-markdown.github.io/extensions/toc/ + +#### Linking to images and media As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media. For example, if your project documentation needed to include a [GitHub pages -CNAME -file](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) -and a PNG formatted screenshot image then your file layout might look as -follows: +CNAME file] and a PNG formatted screenshot image then your file layout might +look as follows: ```no-highlight mkdocs.yml @@ -180,15 +275,89 @@ Cupcake indexer is a snazzy new project for indexing small cakes. *Above: Cupcake indexer in progress* ``` -You image will now be embedded when you build the documentation, and should also -be previewed if you're working on the documentation with a Markdown editor. +Your image will now be embedded when you build the documentation, and should +also be previewed if you're working on the documentation with a Markdown editor. -## Markdown extensions +[GitHub pages CNAME file]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ -MkDocs supports the following Markdown extensions. +### Meta-Data + +MkDocs includes support for [MultiMarkdown] style meta-data (often called +front-matter). Meta-data consists of a series of keywords and values defined at +the beginning of a Markdown document like this: + +```no-highlight +Title: My Document +Summary: A brief description of my document. +Authors: Waylan Limberg + Tom Christie +Date: January 23, 2018 +blank-value: +some_url: http://example.com + +This is the first paragraph of the document. +``` + +The keywords are case-insensitive and may consist of letters, numbers, +underscores and dashes and must end with a colon. The values consist of anything +following the colon on the line and may even be blank. + +If a line is indented by 4 or more spaces, that line is assumed to be an +additional line of the value for the previous keyword. A keyword may have as +many lines as desired. + +The first blank line ends all meta-data for the document. Therefore, the first +line of a document must not be blank. + +Alternatively, you may use YAML style deliminators to mark the start and/or end +of your meta-data. When doing so, the first line of your document must be `---`. +The meta-data ends at the first blank line or the first line containing an end +deliminator (either `---` or `...`), whichever comes first. Even though YAML +deliminators are supported, meta-data is not parsed as YAML. + +All meta-data is stripped from the document prior to being processing by +Python-Markdown. The keys and values are passed by MkDocs to the page template. +Therefore, if a theme includes support, the values of any keys can be displayed +on the page. See the documentation for your theme for information about which +keys may be supported, if any. + +In addition to displaying information in a template, MkDocs includes support for +a few predefined meta-data keys which can alter the behavior of MkDocs for that +specific page. The following keys are supported: + +`template`: + +: The template to use with the current page. + + By default, MkDocs uses the `main.html` template of a theme to render + Markdown pages. You can use the `template` meta-data key to define a + different template file for that specific page. The template file must be + available on the path(s) defined in the theme's environment. + +`title`: + +: The "title" to use for the document. + + MkDocs will attempt to determine the title of a document in the following + ways, in order: + + 1. A title defined in the [pages] configuration setting for a document. + 2. A title defined in the `title` meta-data key of a document. + 3. A level 1 Markdown header on the first line of the document body. + 4. The filename of a document. + + Upon finding a title for a page, MkDoc does not continue checking any + additional sources in the above list. + +[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata +[pages]: configuration.md#pages ### Tables +The [tables] extension adds a basic table syntax to Markdown which is popular +across multiple implementations. The syntax is rather simple and is generally +only useful for simple tabular data. + A simple table looks like this: ```no-highlight @@ -216,8 +385,17 @@ Left | Center | Right Left | Center | Right ``` +Note that table cells cannot contain any block level elements and cannot contain +multiple lines of text. They can, however, include inline Markdown as defined in +Markdown's [syntax] rules. + +[tables]: https://python-markdown.github.io/extensions/tables/ + ### Fenced code blocks +The [fenced code blocks] extension adds an alternate method of defining code +blocks without indentation. + The first line should contain 3 or more backtick (`` ` ``) characters, and the last line should contain the same number of backtick characters (`` ` ``): @@ -232,7 +410,7 @@ code block. ~~~ With this approach, the language can optionally be specified on the first line -after the backticks: +after the backticks which informs any syntax highlighters of the language used: ~~~no-highlight ```python @@ -240,3 +418,8 @@ def fn(): pass ``` ~~~ + +Note that fenced code blocks can not be indented. Therefore, they cannot be +nested inside list items, blockquotes, etc. + +[fenced code blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/ diff --git a/mdl_ruleset.rb b/mdl_ruleset.rb index e0312822..7016b57a 100644 --- a/mdl_ruleset.rb +++ b/mdl_ruleset.rb @@ -2,3 +2,6 @@ all # Use all markdownlint rules # Disable line length check for tables and code blocks rule 'MD013', :line_length => 80, :code_blocks => false, :tables => false + +# Set Ordered list item prefix to "ordered" (use 1. 2. 3. not 1. 1. 1.) +rule 'MD029', :style => "ordered"