mkdocs | Project documentation with Markdown | Static Site Generator library

 by   mkdocs Python Version: 1.6.0 License: BSD-2-Clause

kandi X-RAY | mkdocs Summary

kandi X-RAY | mkdocs Summary

mkdocs is a Python library typically used in Web Site, Static Site Generator applications. mkdocs has no bugs, it has no vulnerabilities, it has build file available, it has a Permissive License and it has high support. You can install using 'pip install mkdocs' or download it from GitHub, PyPI.

Project documentation with Markdown. MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with third-party themes, plugins, and Markdown extensions. Please see the Documentation for an introductory tutorial and a full user guide.

            kandi-support Support

              mkdocs has a highly active ecosystem.
              It has 16556 star(s) with 2255 fork(s). There are 232 watchers for this library.
              There were 1 major release(s) in the last 6 months.
              There are 111 open issues and 1698 have been closed. On average issues are closed in 408 days. There are 13 open pull requests and 0 closed requests.
              It has a negative sentiment in the developer community.
              The latest version of mkdocs is 1.6.0

            kandi-Quality Quality

              mkdocs has 0 bugs and 0 code smells.

            kandi-Security Security

              mkdocs has no vulnerabilities reported, and its dependent libraries have no vulnerabilities reported.
              mkdocs code analysis shows 0 unresolved vulnerabilities.
              There are 0 security hotspots that need review.

            kandi-License License

              mkdocs is licensed under the BSD-2-Clause License. This license is Permissive.
              Permissive licenses have the least restrictions, and you can use them in most projects.

            kandi-Reuse Reuse

              mkdocs releases are available to install and integrate.
              Deployable package is available in PyPI.
              Build file is available. You can build the component from source.
              mkdocs saves you 4042 person hours of effort in developing the same functionality from scratch.
              It has 10455 lines of code, 845 functions and 115 files.
              It has medium code complexity. Code complexity directly impacts maintainability of the code.

            Top functions reviewed by kandi - BETA

            kandi has reviewed mkdocs and discovered the below as its top functions. This is intended to give you an instant insight into mkdocs implemented functionality, and help decide if they suit your requirements.
            • Serve a build directory
            • Return a relative path to the current working directory
            • Start the server
            • Runs the build loop
            • Deploy the project to GitHub
            • Check git version
            • Return the host and path for a given remote
            • Get the SHA of the current HEAD of the current repo
            • Initialize docs
            • Run gh - deployment
            • Handle data
            • Run language search
            • Validate the configuration
            • Handle opening tags
            • Run the validation steps
            • Initialize the options
            • Returns the destination path
            • Draw an edge
            • Validate the theme
            • Replace URLs with links
            • Load a configuration file
            • Extract data from a docstring
            • Validate config data
            • Set edit url
            • Handle the request
            • Generate search index files
            Get all kandi verified functions for this library.

            mkdocs Key Features

            No Key Features are available at this moment for mkdocs.

            mkdocs Examples and Code Snippets

            Pythondot img1Lines of Code : 93dot img1License : Permissive (Apache-2.0)
            copy iconCopy
            # /mkdocs.yml
            site_name: Cats API
              - Intro: ''
              - Authentication: ''
              - API:
                - v1: '!include ./v1/mkdocs.yml'
                - v2: '!include ./v2/mkdocs.yml'
              - monorepo
            # /src/v1/mkdocs.yml
            site_name: versions/  
            mkdocs-mermaid2-plugin,Usage,Adding a Javascript callback function
            Pythondot img2Lines of Code : 20dot img2License : Permissive (MIT)
            copy iconCopy
            // js/extra.js
            function myMermaidCallbackFunction(id) {
              console.log('myMermaidCallbackFunction', id);
              - mermaid2:
                    theme: dark
                        callback: ^myMermaidCallbackFunction
            mkdocs-mermaid2-plugin,Using the mermaid2.dumps() function
            Pythondot img3Lines of Code : 18dot img3License : Permissive (MIT)
            copy iconCopy
            foo = MyFunctioName
            import mermaid2
            obj = { "hello": "world", 
                "barbaz": "^bazbar",
                "foo": {"bar": 2},
                "bar": True}
            s = mermaid2.dumps(obj)
                hello: "world",
                barbaz: bazbar,
                foo: {
                    bar: 2
                bar: true
            How to install extra-requires from a github link with `pip`
            Pythondot img4Lines of Code : 2dot img4License : Strong Copyleft (CC BY-SA 4.0)
            copy iconCopy
            pip install "mkdocs[i18n] @ git+"
            __pycache__ merge conflicts not resolved by gitignore
            Pythondot img5Lines of Code : 8dot img5License : Strong Copyleft (CC BY-SA 4.0)
            copy iconCopy
            CONFLICT (rename/delete):
            astroid/brain/__pycache__/brain_subprocess.cpython-37 2.pyc
            deleted in version3ascii and renamed to
            in HEAD. 
            Mkdocs is not found, but possible to uninstall on macOS
            Pythondot img6Lines of Code : 6dot img6License : Strong Copyleft (CC BY-SA 4.0)
            copy iconCopy
            sudo pip3 install mkdocs
            sudo pip3 install mkdocs-material
            sudo pip3 install matplotlib
            mkdocs serve
            Syntax highlighted code block in markdown indented list paragraph
            Pythondot img7Lines of Code : 6dot img7License : Strong Copyleft (CC BY-SA 4.0)
            copy iconCopy
            3. But what about syntax highlighted code?
            ~~~~ bash
            echo "This won't work"
            copy iconCopy
            from django.views.static import serve
            path('static//', serve, {'document_root': settings.STATIC_ROOT, }),
            Sphinx docs builds fail on readthedocs for private GitHub repository
            Pythondot img9Lines of Code : 8dot img9License : Strong Copyleft (CC BY-SA 4.0)
            copy iconCopy
             Advanced ($150 per month)
            Plan Features:
            Style your documentation to fit your company's brand
            Support custom SSL certificates
            Host documentation on your own domain
            Auto-build an Mkdocs documentation in Travis CI
            Pythondot img10Lines of Code : 28dot img10License : Strong Copyleft (CC BY-SA 4.0)
            copy iconCopy
            language: python # Set the build language to Python
            python: 3.6 # Set the version of Python to use
            branches: master # Set the branch to build from
                - pip install mkdocs # Install the required dependencies
            script: true # Ski

            Community Discussions


            Unable to build a docker image following Docker Tutorial
            Asked 2022-Apr-04 at 22:25

            I was following this tutorial on a Macbook to build a sample Docker image but when I tried to run the following command:



            Answered 2021-Oct-06 at 13:31

            See its Dockerfile, it uses FROM python:alpine AS base, which means it used a shared tag. Another word, at the time the document wrote, python:alpine means maybe python:3.9-alpine or others.

            But now, it means python:3.10-alpine, see this.

            The problems happens at mkdocs itself, it uses next code:



            Mkdocs "can not display mermaid in the right way"
            Asked 2022-Mar-12 at 13:10

            I try to use this theme plugin to display the graph


            the settings file:



            Answered 2022-Mar-12 at 13:10

            This was part of the insiders offer at your time. If you upgrade your mkdocs-material version it should work.




            Support extended markdown table syntax with Mkdocs
            Asked 2022-Feb-15 at 20:25

            I have markdown tables like the following in my docs:



            Answered 2022-Feb-15 at 20:25

            Thanks to the link Waylan provided, I found an unmaintained project that provides what I needed.

            I've made a fork of the project (which I intend to maintain), and have published it to PyPI.



            Indented paragraph in bullet list not rendering correctly
            Asked 2022-Feb-02 at 13:36

            I'm using MkDocs to build my documentation.

            In my .md file I have the following content:



            Answered 2022-Jan-20 at 17:57

            Markdown content blocks (for list continuations, source blocks, etc.) require an indent of 4 spaces or 1 tab. See

            Either change your two-space indent to 4 spaces, or use tabs.

            If you use tabs, you might be able to set the tabstop distance to 2, to preserve the editing experience that you currently have.



            How to serve static site with flask
            Asked 2022-Jan-24 at 07:14

            I use MKdocs to create a very sensitive documentation, and I want it to be securely available online.
            My project is:

            • [V] create an encrypted volume on a server (I used veracrypt, cli and python compatibility)
            • [V] making a simple page to ask for the key to decrypt
            • [V] decrypt the volume
            • [X] serve site on flask
            • [V] detect session closure and encrypt volume again

            (this way there is no persistent clear data on the server)

            Documentation gets edited only locally, encrypted and rsynced to server.

            Now, I'm blocked on serving site on flask step, because the MKdocs site is structured like this:



            Answered 2022-Jan-22 at 09:32

            We can consider MkDocs's rendered HTML pages as simple Flask templates. So all we have to do is to create a Flask endpoint that first do the permissions-checking then based on the URL, serves the rendered MkDocs HTML file or a related static file.

            Let's call our new endpoint bridge. First, put everything from MkDocs site directory to Flask's templates/bridge directory. My example MkDocs tree looks like this:



            user table not created on django deployment but superuser created on heroku bash
            Asked 2022-Jan-18 at 21:06

            I'm trying to upload my first django app and I've been struggle with this issue for sometime, help is appreciated.

            I already set up my project to be on heroku, I followed this tutorial: in which django_heroku module is used to configure DB, here is the link to library

            The app throws the error on login as if user tables didn't exist but I already create a super user using the heroku bash feature, after apply migrations using "heroku run python migrate". When I run "ls" command on heroku bash this is my directory:

   Procfile requirements.txt runtime.txt smoke staticfile

            "smoke" is my folder app, should I could see the db in this directory? if the db was not created how could I create a superuser using heroku bash feature?

            This is the DB configuration that django gives me on server:



            Answered 2022-Jan-18 at 21:06

            If you look at the django-heroku repository on GitHub I think you'll find that it has been abandoned. It has a banner saying

            This repository has been archived by the owner. It is now read-only.

            and has not had a new commit on the master branch since October, 2018.

            The heroku-on-django library aims to be an updated replacement for django-heroku:

            This has been forked from django-heroku because it was abandoned and then renamed to django-on-heroku because old project has been archived.

            It is also somewhat stagnant (the most recent commit to master at the time of writing is from October, 2020) but it should work better than django-heroku.

            In either case, make sure to put this at the bottom of your as indicated in the documentation:



            Right way to change mkdocs markdown toc title "table of contents"?
            Asked 2021-Dec-09 at 11:27

            I'm using mkdocs with material layout and toc markdown extension for adding a toc to the right for a documentation project.

            I use up42's wiki as a template for my wiki. I would like to change the title "Table of contents".

            The toc markdown documentation provides a parameter "title" that doesn't change anything when used in my mkdocs.yml:



            Answered 2021-Nov-09 at 11:45
            Using CSS

            I didn't find the right parameter or the problem yet, but a simple CSS overset does the job pretty well (thanks to this answer):



            Is there a way to add some basic scripting to MkDocs when writing in MarkDown?
            Asked 2021-Nov-28 at 12:11

            I have a documentation site using MkDocs. It contains a list of documents, all with the same basic structure (we only have a list of experimental notebooks). Each notebook (written in a separate MarkDown file) should contain an author + date in the beginning using the following:



            Answered 2021-Nov-28 at 12:11

            You may want to use metadata also called frontend data, as described in the yaml-style-meta-data section. Such information is placed at the beginning of your markdown file. The content can then be used to generate content.

            The macro plugin is made for this and can be found here



            How to install extra-requires from a github link with `pip`
            Asked 2021-Oct-15 at 11:58

            I have this python package located in a github repository. I can install it from the github link directly like so :



            Answered 2021-Oct-15 at 06:07


            How to embed a local pdf file in mkdocs generated website on github-pages?
            Asked 2021-Sep-23 at 00:50

            I have a private repository with some pdf files among others. The content is however, made publicly available using MkDocs (material) and github-pages. I want to embed these locally available pdf files on the website (created with MkDocs). So far I have tried this:



            Answered 2021-Sep-22 at 16:10

            The main challenge in making the pdf file available on the published site is creating a link that is not broken and actually accesses the file from the repository.

            Mkdocs comes with a lot of extensions, that enhance the functionality of the framework. You need to use pymdownx.pathconverter to address this issue.


            I have blurred out the contents from the screenshot. But you can see how the embedded pdf file looks like.

            Here are the pieces you need to work with.

            A. Install PyMdown Extension

            Along with Other must haves...


            Community Discussions, Code Snippets contain sources that include Stack Exchange Network


            No vulnerabilities reported

            Install mkdocs

            You can install using 'pip install mkdocs' or download it from GitHub, PyPI.
            You can use mkdocs like any standard Python library. You will need to make sure that you have a development environment consisting of a Python distribution including header files, a compiler, pip, and git installed. Make sure that your pip, setuptools, and wheel are up to date. When using pip it is generally recommended to install packages in a virtual environment to avoid changes to the system.


            If you need help with MkDocs, do not hesitate to get in contact with us!. Please note that we may only provide support for problems/questions regarding core features of MkDocs. Any questions or bug reports about features of third-party themes, plugins, extensions or similar should be made to their respective projects. But, such questions are not banned from the chat room.
            Find more information at:

            Find, review, and download reusable Libraries, Code Snippets, Cloud APIs from over 650 million Knowledge Items

            Find more libraries
          • PyPI

            pip install mkdocs

          • CLONE
          • HTTPS


          • CLI

            gh repo clone mkdocs/mkdocs

          • sshUrl


          • Stay Updated

            Subscribe to our newsletter for trending solutions and developer bootcamps

            Agree to Sign up and Terms & Conditions

            Share this Page

            share link

            Explore Related Topics

            Consider Popular Static Site Generator Libraries


            by gohugoio


            by gatsbyjs


            by jekyll


            by mkdocs


            by 11ty

            Try Top Libraries by mkdocs


            by mkdocsPython


            by mkdocsPython


            by mkdocsCSS


            by mkdocsPython


            by mkdocsCSS