The Markdown Guide is a free and open-source reference guide that explains how to use Markdown, the simple and easy-to-use markup language you can use to format virtually any document. Get Started DigitalOcean App Platform, a new PaaS that gets your apps to market, faster. We like to keep documentation in bitbucket as well, in markdown format. It's very limiting not to be able to have comments (that will not render) in the document. StackEdit can sync your files with Google Drive, Dropbox and GitHub. It can also publish them as blog posts to Blogger, WordPress and Zendesk. You can choose whether to upload in Markdown format, HTML, or to format the output using the Handlebars template engine.

• Bitbucket Readme Markup
• Markdown Bitbucket Code
• Markdown Bitbucket For Windows

Guide to all available configuration settings.

Introduction

Project settings are always configured by using a YAML configuration file in theproject directory named mkdocs.yml.

As a minimum this configuration file must contain the site_name setting. Allother settings are optional.

Project information

site_name

This is a required setting, and should be a string that is used as the maintitle for the project documentation. For example:

When rendering the theme this setting will be passed as the site_name contextvariable.

site_url

Set the canonical URL of the site. This will add a link tag with the canonicalURL to the generated HTML header.

default: null

repo_url

When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ..)on each page.

default: null

repo_name

When set, provides the name for the link to your repository on each page.

default: 'GitHub', 'Bitbucket' or 'GitLab' if the repo_url matchesthose domains, otherwise the hostname from the repo_url.

edit_uri

Path from the base repo_url to the docs directory when directly viewing apage, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,etc), the branch, and the docs directory itself. MkDocs concatenates repo_urland edit_uri, and appends the input path of the page.

When set, and if your theme supports it, provides a link directly to the page inyour source repository. This makes it easier to find and edit the source for thepage. If repo_url is not set, this option is ignored. On some themes, settingthis option may cause an edit link to be used in place of a repository link.Other themes may show both links.

The edit_uri supports query ('?') and fragment ('#') characters. Forrepository hosts that use a query or a fragment to access the files, theedit_uri might be set as follows. (Note the ? and # in the URI..)

For other repository hosts, simply specify the relative path to the docsdirectory.

Note

On a few known hosts (specifically GitHub, Bitbucket and GitLab), theedit_uri is derived from the 'repo_url' and does not need to be setmanually. Simply defining a repo_url will automatically populate theedit_uri configs setting.

For example, for a GitHub- or GitLab-hosted repository, the edit_uriwould be automatically set as edit/master/docs/ (Note the edit pathand master branch).

For a Bitbucket-hosted repository, the equivalent edit_uri would beautomatically set as src/default/docs/ (note the src path and defaultbranch).

To use a different URI than the default (for example a different branch),simply set the edit_uri to your desired string. If you do not want any'edit URL link' displayed on your pages, then set edit_uri to an emptystring to disable the automatic setting.

Warning

On GitHub and GitLab, the default 'edit' path (edit/master/docs/) opensthe page in the online editor. This functionality requires that the userhave and be logged in to a GitHub/GitLab account. Otherwise, the user willbe redirected to a login/signup page. Alternatively, use the 'blob' path(blob/master/docs/) to open a read-only view, which supports anonymousaccess.

default: edit/master/docs/ for GitHub and GitLab repos orsrc/default/docs/ for a Bitbucket repo, if repo_url matches those domains,otherwise null

site_description

Set the site description. This will add a meta tag to the generated HTML header.

default: null

site_author

Set the name of the author. This will add a meta tag to the generated HTMLheader.

default: null

copyright

Set the copyright information to be included in the documentation by the theme.

default: null

google_analytics

Set the Google analytics tracking configuration.

default: null

remote_branch

Set the remote branch to commit to when using gh-deploy to deploy to GithubPages. This option can be overridden by a command line option in gh-deploy.

default: gh-pages

remote_name

Set the remote name to push to when using gh-deploy to deploy to Github Pages.This option can be overridden by a command line option in gh-deploy.

default: origin

Documentation layout

nav

This setting is used to determine the format and layout of the global navigationfor the site. A minimal navigation configuration could look like this:

All paths must be relative to the mkdocs.yml configuration file. See thesection on configuring pages and navigation for a more detailed breakdown,including how to create sub-sections.

Navigation items may also include links to external sites. While titles areoptional for internal links, they are required for external links. An externallink may be a full URL or a relative URL. Any path which is not found in thefiles is assumed to be an external link. See the section about [Meta-Data] onhow MkDocs determines the page title of a document.

In the above example, the first two items point to local files while the thirdpoints to an external site.

However, sometimes the MkDocs site is hosted in a subdirectory of a project'ssite and you may want to link to other parts of the same site without includingthe full domain. In that case, you may use an appropriate relative URL.

In the above example, two different styles of external links are used. Firstnote that the site_url indicates that the MkDocs site is hosted in the /foo/subdirectory of the domain. Therefore, the Home navigation item is a relativelink which steps up one level to the server root and effectively points tohttps://example.com/. The Bug Tracker item uses an absolute path from theserver root and effectively points to https://example.com/bugs/. Of course, theUser Guide points to a local MkDocs page.

default: By default nav will contain an alphanumerically sorted, nestedlist of all the Markdown files found within the docs_dir and itssub-directories. Index files will always be listed first within a sub-section.

Build directories

theme

Sets the theme and theme specific configuration of your documentation site.May be either a string or a set of key/value pairs.

If a string, it must be the string name of a known installed theme. For a listof available themes visit styling your docs.

An example set of key/value pairs might look something like this:

If a set of key/value pairs, the following nested keys can be defined:

name:

The string name of a known installed theme. For a list of available themesvisit styling your docs.

custom_dir:

A directory containing a custom theme. This can either be a relativedirectory, in which case it is resolved relative to the directory containingyour configuration file, or it can be an absolute directory path from theroot of your local file system.

See styling your docs for details if you would like to tweak anexisting theme.

See custom themes if you would like to build your own theme from theground up.

static_templates:

Bitbucket Readme Markup

A list of templates to render as static pages. The templates must be locatedin either the theme's template directory or in the custom_dir defined inthe theme configuration.

(theme specific keywords)

Any additional keywords supported by the theme can also be defined. See thedocumentation for the theme you are using for details.

default: 'mkdocs'

docs_dir

The directory containing the documentation source markdown files. This caneither be a relative directory, in which case it is resolved relative to thedirectory containing your configuration file, or it can be an absolute directorypath from the root of your local file system.

default: 'docs'

site_dir

The directory where the output HTML and other files are created. This can eitherbe a relative directory, in which case it is resolved relative to the directorycontaining your configuration file, or it can be an absolute directory path fromthe root of your local file system.

default: 'site'

Note:

If you are using source code control you will normally want to ensure thatyour build output files are not committed into the repository, and onlykeep the source files under version control. For example, if using gityou might add the following line to your .gitignore file:

If you're using another source code control tool, you'll want to check itsdocumentation on how to ignore specific directories.

extra_css

Set a list of CSS files in your docs_dir to be included by the theme. Forexample, the following example will include the extra.css file within thecss subdirectory in your docs_dir.

default: [] (an empty list).

extra_javascript

Set a list of JavaScript files in your docs_dir to be included by the theme.See the example in extra_css for usage.

default: [] (an empty list).

extra_templates

Set a list of templates in your docs_dir to be built by MkDocs. To see moreabout writing templates for MkDocs read the documentation about custom themesand specifically the section about the variables that are available totemplates. See the example in extra_css for usage.

default: [] (an empty list). Ronan density meter.

extra

A set of key value pairs, where the values can be any valid YAML construct, thatwill be passed to the template. This allows for great flexibility when creatingcustom themes.

For example, if you are using a theme that supports displaying the projectversion, you can pass it to the theme like this:

default: By default extra will be an empty key value mapping. Smadav antivirus 2018 key.

Preview controls

use_directory_urls

This setting controls the style used for linking to pages within thedocumentation.

The following table demonstrates how the URLs used on the site differ whensetting use_directory_urls to true or false.

The default style of use_directory_urls: true creates more user friendly URLs,and is usually what you'll want to use.

The alternate style can occasionally be useful if you want your documentation toremain properly linked when opening pages directly from the file system, becauseit creates links that point directly to the target file rather than the targetdirectory.

default: true

strict

Determines how warnings are handled. Set to true to halt processing when awarning is raised. Set to false to print a warning and continue processing.

default: false

dev_addr

Determines the address used when running mkdocs serve. Must be of the formatIP:PORT.

Allows a custom default to be set without the need to pass it through the--dev-addr option every time the mkdocs serve command is called.

default: '127.0.0.1:8000'

Formatting options

markdown_extensions

MkDocs uses the Python Markdown library to translate Markdown filesinto HTML. Python Markdown supports a variety of extensionsthat customize how pages are formatted. This setting lets you enable a list ofextensions beyond the ones that MkDocs uses by default (meta, toc, tables,and fenced_code).

For example, to enable the SmartyPants typography extension, use:

Some extensions provide configuration options of their own. If you would like toset any configuration options, then you can nest a key/value mapping(option_name: option value) of any options that a given extension supports.See the documentation for the extension you are using to determine what optionsthey support.

Markdown Bitbucket Code

For example, to enable permalinks in the (included) toc extension, use:

Note that a colon (:) must follow the extension name (toc) and then on a newline the option name and value must be indented and separated by a colon. If youwould like to define multiple options for a single extension, each option must bedefined on a separate line:

Add an additional item to the list for each extension. If you have noconfiguration options to set for a specific extension, then simply omit optionsfor that extension:

Markdown Bitbucket For Windows

See Also:

The Python-Markdown documentation provides a list of extensionswhich are available out-of-the-box. For a list of configuration optionsavailable for a given extension, see the documentation for that extension.

You may also install and use various third party extensions. Consultthe documentation provided by those extensions for installation instructionsand available configuration options.

default: [] (an empty list).

plugins

A list of plugins (with optional configuration settings) to use when buildingthe site . See the Plugins documentation for full details.

If the plugins config setting is defined in the mkdocs.yml config file, thenany defaults (such as search) are ignored and you need to explicitly re-enablethe defaults if you would like to continue using them:

To completely disable all plugins, including any defaults, set the pluginssetting to an empty list:

default: ['search'] (the 'search' plugin included with MkDocs).

Search

A search plugin is provided by default with MkDocs which uses lunr.js as asearch engine. The following config options are available to alter the behaviorof the search plugin:

separator

A regular expression which matches the characters used as word separators whenbuilding the index. By default whitespace and the hyphen (-) are used. To addthe dot (.) as a word separator you might do this:

default: '[s-]+'

min_search_length

An integer value that defines the minimum length for a search query. By defaultsearches shorter than 3 chars in length are ignored as search result quality withshort search terms is poor. However, for some use cases (such as documentationabout Message Queues which might generate searches for 'MQ') it may be preferableto set a shorter limit.

default: 3

lang

A list of languages to use when building the search index as identified by theirISO 639-1 language codes. With Lunr Languages, the following languages aresupported:

• ar: Arabic
• da: Danish
• nl: Dutch
• en: English
• fi: Finnish
• fr: French
• de: German
• hu: Hungarian
• it: Italian
• ja: Japanese
• no: Norwegian
• pt: Portuguese
• ro: Romanian
• ru: Russian
• es: Spanish
• sv: Swedish
• th: Thai
• tr: Turkish
• vi: Vietnamese

You may contribute additional languages.

Warning

While search does support using multiple languages together, it is best notto add additional languages unless you really need them. Each additionallanguage adds significant bandwidth requirements and uses more browserresources. Generally it is best to keep each instance of MkDocs to a singlelanguage.

Note

Lunr Languages does not currently include support for Chinese or other Asianlanguages. However, some users have reported decent results using Japanese.

default: ['en']

prebuild_index

Optionally generates a pre-built index of all pages, which provides someperformance improvements for larger sites. Before enabling, check that thetheme you are using explicitly supports using a prebuilt index (the builtinthemes do).

There are two options for prebuilding the index:

Using Node.js setting prebuild_index to True or node. This optionrequires that Node.js be installed and the command node be on the systempath. If this feature is enabled and fails for any reason, a warning is issued.You may use the --strict flag when building to cause such a failure to raisean error instead.

Using Lunr.py setting prebuild_index to python. Lunr.py is installedas part of mkdocs and guarantees compatibility with Lunr.js even on languagesother than english. If you find substantial inconsistencies or problems pleasereport it on Lunr.py's issues and fall back to the Node.js version.

Note

On smaller sites, using a pre-built index is not recommended as it creates asignificant increase is bandwidth requirements with little to no noticeableimprovement to your users. However, for larger sites (hundreds of pages),the bandwidth increase is relatively small and your users will notice asignificant improvement in search performance.

default: False