How to layout and write your Markdown source files.
Your documentation source should be written as regular Markdown files (seeWriting with Markdown below), and placed in thedocumentation directory. By default, this directorywill be named
docs and will exist at the top level of your project, alongsidethe
mkdocs.yml configuration file. Mark kermode knives out.
事象: pipコマンドを使ったらYou are using pip version 20.1.1; however, version 20.2.4 is available.となった環境Windows10 Pro 6. MkDocs has 6 repositories available. Follow their code on GitHub. Python Types Intro¶ Python has support for optional 'type hints'. These 'type hints' are a special syntax that allow declaring the type of a variable. By declaring types for your variables, editors and tools can give you better support. This is just a quick tutorial / refresher about Python type hints. Python Python Numbers Variables Sequences Functions Logic Loops Text Modules and Packages SciPy SciPy NumPy Matplotlib SciPy Roots and Optimization Roots and Optimization Root Finding Bisection Method Secant Method Newton's Method.
The simplest project you can create will look something like this:
By convention your project homepage should be named
index.md (see Indexpages below for details). Any of the following fileextensions may be used for your Markdown source files:
md. All Markdown files included in your documentationdirectory will be rendered in the built site regardless of any settings.
Files and directories with names which begin with a dot (for example:
.bar/baz.md) are ignored by MkDocs, which matches thebehavior of most web servers. There is no option to override thisbehavior.
You can also create multi-page documentation, by creating several Markdownfiles:
The file layout you use determines the URLs that are used for the generatedpages. Given the above layout, pages would be generated for the following URLs:
You can also include your Markdown files in nested directories if that bettersuits your documentation layout.
Source files inside nested directories will cause pages to be generated withnested URLs, like so:
Any files which are not identified as Markdown files (by their file extension)within the documentation directory are copied byMkDocs to the built site unaltered. See [how to link to images and media](#linking_to_images_and_media) below for details.
When a directory is requested, by default, most web servers will return an indexfile (usually named
index.html) contained within that directory if one exists.For that reason, the homepage in all of the examples above has been named
index.md, which MkDocs will render to
index.html when building the site.
Many repository hosting sites provide special treatment for README files bydisplaying the contents of the README file when browsing the contents of adirectory. Therefore, MkDocs will allow you to name your index pages as
README.md instead of
index.md. In that way, when users are browsing yoursource code, the repository host can display the index page of that directory asit is a README file. However, when MkDocs renders your site, the file will berenamed to
index.html so that the server will serve it as a proper index file.
If both an
index.md file and a
README.md file are found in the samedirectory, then the
index.md file is used and the
README.md file isignored.
Configure Pages and Navigation
The nav configuration setting in your
mkdocs.yml filedefines which pages are included in the global site navigation menu as well asthe structure of that menu. If not provided, the navigation will beautomatically created by discovering all the Markdown files in thedocumentation directory. An automatically creatednavigation configuration will always be sorted alphanumerically by file name(except that index files will always be listed first within a sub-section). Youwill need to manually define your navigation configuration if you would likeyour navigation menu sorted differently.
A minimal navigation configuration could look like this:
All paths in the navigation configuration must be relative to the
docs_dirconfiguration option. If that option is set to the default value,
docs, thesource files for the above configuration would be located at
The above example will result in two navigation items being created at the toplevel and with their titles inferred from the contents of the Markdown file or,if no title is defined within the file, of the file name. To override the titlein the
nav setting add a title right before the filename.
Note that if a title is defined for a page in the navigation, that title will beused throughout the site for that page and will override any title definedwithin the page itself.
Navigation sub-sections can be created by listing related pages together under asection title. For example:
With the above configuration we have three top level items: 'Home', 'User Guide'and 'About.' 'Home' is a link to the homepage for the site. Under the 'UserGuide' section two pages are listed: 'Writing your docs' and 'Styling yourdocs.' Under the 'About' section two more pages are listed: 'License' and'Release Notes.'
Note that a section cannot have a page assigned to it. Sections are onlycontainers for child pages and sub-sections. You may nest sections as deeply asyou like. However, be careful that you don't make it too difficult for yourusers to navigate through the site navigation by over-complicating the nesting.While sections may mirror your directory structure, they do not have to.
Any pages not listed in your navigation configuration will still be rendered andincluded with the built site, however, they will not be linked from the globalnavigation and will not be included in the
next links. Suchpages will be 'hidden' unless linked to directly.
Writing with Markdown
MkDocs pages must be authored in Markdown, a lightweight markup languagewhich results in easy-to-read, easy-to-write plain text documents that can beconverted 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 referenceimplementation, although there are a few very minor differences.
In addition to the base Markdown syntax which is common across all Markdownimplementations, MkDocs includes support for extending the Markdown syntax withPython-Markdown extensions. See the MkDocs' markdown_extensionsconfiguration setting for details on how to enable extensions.
MkDocs includes some extensions by default, which are highlighted below.
MkDocs allows you to interlink your documentation by using regular Markdownlinks. However, there are a few additional benefits to formatting those linksspecifically for MkDocs as outlined below.
Linking to pages
When linking between pages in the documentation you can simply use the regularMarkdown linking syntax, including the relative path to the Markdowndocument you wish to link to.
When the MkDocs build runs, these Markdown links will automatically betransformed into an HTML hyperlink to the appropriate HTML page.
Using absolute paths with links is not officially supported. Relative pathsare adjusted by MkDocs to ensure they are always relative to the page. Absolutepaths are not modified at all. This means that your links using absolute pathsmight work fine in your local environment but they might break once you deploythem to your production server.
If the target documentation file is in another directory you'll need to makesure to include any relative directory path in the link.
The toc extension is used by MkDocs to generate an ID for every header in yourMarkdown documents. You can use that ID to link to a section within a targetdocument by using an anchor link. The generated HTML will correctly transformthe path portion of the link, and leave the anchor portion intact.
Note that IDs are created from the text of a header. All text is converted tolowercase and any disallowed characters, including white-space, are converted todashes. Consecutive dashes are then reduced to a single dash.
There are a few configuration settings provided by the toc extension which youcan set in your
mkdocs.yml configuration file to alter the default behavior:
Generate permanent links at the end of each header. Default:
When set to True the paragraph symbol (¶ or
¶) is used as thelink text. When set to a string, the provided string is used as the linktext. For example, to use the hash symbol (
#) instead, do:
Base level for headers. Default:
This setting allows the header levels to be automatically adjusted to fitwithin the hierarchy of your HTML templates. For example, if the Markdowntext for a page should not contain any headers higher than level 2 (
Then any headers in your document would be increased by 1. For example, theheader
# Header would be rendered as a level 2 header (
<h2>) in the HTMLoutput.
Word separator. Default:
Character which replaces white-space in generated IDs. If you preferunderscores, then do:
Note that if you would like to define multiple of the above settings, you mustdo so under a single
toc entry in the
Linking to images and media
As well as the Markdown source files, you can also include other file types inyour documentation, which will be copied across when generating yourdocumentation site. These might include images and other media.
For example, if your project documentation needed to include a GitHub pagesCNAME file and a PNG formatted screenshot image then your file layout mightlook as follows:
To include images in your documentation source files, simply use any of theregular Markdown image syntaxes:
Your image will now be embedded when you build the documentation, and shouldalso be previewed if you're working on the documentation with a Markdown editor.
Linking from raw HTML
Markdown allows document authors to fall back to raw HTML when the Markdownsyntax does not meets the author's needs. MkDocs does not limit Markdown in thisregard. However, as all raw HTML is ignored by the Markdown parser, MkDocs isnot able to validate or convert links contained in raw HTML. When includinginternal links within raw HTML, you will need to manually format the linkappropriately for the rendered document.
MkDocs includes support for both YAML and MultiMarkdown style meta-data (oftencalled front-matter). Meta-data consists of a series of keywords and valuesdefined at the beginning of a Markdown document, which are stripped from thedocument prior to it being processing by Python-Markdown. The key/value pairsare passed by MkDocs to the page template. Therefore, if a theme includessupport, the values of any keys can be displayed on the page or used to controlthe page rendering. See your theme's documentation for information about whichkeys may be supported, if any.
In addition to displaying information in a template, MkDocs includes support fora few predefined meta-data keys which can alter the behavior of MkDocs for thatspecific page. The following keys are supported:
The template to use with the current page.
By default, MkDocs uses the
main.html template of a theme to renderMarkdown pages. You can use the
template meta-data key to define adifferent template file for that specific page. The template file must beavailable on the path(s) defined in the theme's environment.
The 'title' to use for the document.
MkDocs will attempt to determine the title of a document in the followingways, in order:
- A title defined in the nav configuration setting for a document.
- A title defined in the
titlemeta-data key of a document.
- A level 1 Markdown header on the first line of the document body. Please note that Setext-style headers are not supported.
- The filename of a document.
Upon finding a title for a page, MkDoc does not continue checking anyadditional sources in the above list.
YAML Style Meta-Data
YAML style meta-data consists of YAML key/value pairs wrapped in YAML styledeliminators to mark the start and/or end of the meta-data. The first line ofa document must be
---. The meta-data ends at the first line containing anend deliminator (either
..). The content between the deliminators isparsed as YAML.
YAML is able to detect data types. Therefore, in the above example, the valuesof
some_url are strings, the value of
authors is alist of strings and the value of
date is a
datetime.date object. Note thatthe YAML keys are case sensitive and MkDocs expects keys to be all lowercase.The top level of the YAML must be a collection of key/value pairs, which resultsin a Python
dict being returned. If any other type is returned or the YAMLparser encounters an error, then MkDocs does not recognize the section asmeta-data, the page's
meta attribute will be empty, and the section is notremoved from the document.
MultiMarkdown Style Meta-Data
MultiMarkdown style meta-data uses a format first introduced by theMultiMarkdown project. The data consists of a series of keywords and valuesdefined at the beginning of a Markdown document, like this:
The keywords are case-insensitive and may consist of letters, numbers,underscores and dashes and must end with a colon. The values consist of anythingfollowing 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 anadditional line of the value for the previous keyword. A keyword may have asmany lines as desired. All lines are joined into a single string.
The first blank line ends all meta-data for the document. Therefore, the firstline of a document must not be blank.
MkDocs does not support YAML style deliminators (
..) forMultiMarkdown style meta-data. In fact, MkDocs relies on the the presence orabsence of the deliminators to determine whether YAML style meta-data orMultiMarkdown style meta-data is being used. If the deliminators aredetected, but the content between the deliminators is not valid YAMLmeta-data, MkDocs does not attempt to parse the content as MultiMarkdownstyle meta-data.
The tables extension adds a basic table syntax to Markdown which is popularacross multiple implementations. The syntax is rather simple and is generallyonly useful for simple tabular data.
A simple table looks like this:
If you wish, you can add a leading and tailing pipe to each line of the table:
Specify alignment for each column by adding colons to separator lines:
Note that table cells cannot contain any block level elements and cannot containmultiple lines of text. They can, however, include inline Markdown as defined inMarkdown's syntax rules.
Additionally, a table must be surrounded by blank lines. There must be a blankline before and after the table.
Fenced code blocks
The fenced code blocks extension adds an alternate method of defining codeblocks without indentation.
The first line should contain 3 or more backtick (
`) characters, and thelast line should contain the same number of backtick characters (
With this approach, the language can optionally be specified on the first lineafter the backticks which informs any syntax highlighters of the language used:
Mkdocs Python 3.9
Note that fenced code blocks can not be indented. Therefore, they cannot benested inside list items, blockquotes, etc.
Mkdocs Python 3.8
You're knee deep in learning Pythonprogramming. The syntax is starting to make sense. The firstfew ahh-ha! moments hit you as you learn to useconditional statements,
for loops and classes whilecoding with the open source libraries that make Python such anamazing programming ecosystem.
Now you want to take yourinitial Python knowledgeand make something real, like aweb application to show off tofriends or sell as a service to customers. That's whereFull Stack Pythoncomes in. You have come to the right place to learn everything youneed to create,deploy and operatePython-powered applications.
Full Stack Python is anopen source bookthat explains technical concepts in plain language.Read everything online for free or purchase theSupporter's Editionfor nicely-formatted ebook (PDF, EPUB, MOBI) versions.This guide branches out on topic because your learningrequirements depend on what you're working on. Choose atopic from the links below or view the fulltable of contentsto see even more subjects you can learn.