mkdocs / mkdocs Goto Github PK

View Code? Open in Web Editor NEW

18.3K 234.0 2.4K 31.99 MB

Project documentation with Markdown.

Home Page: https://www.mkdocs.org

License: BSD 2-Clause "Simplified" License

Python 81.00% HTML 4.14% CSS 1.51% JavaScript 13.35%

mkdocs documentation static-site-generator markdown python

mkdocs's Introduction

MkDocs

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.

Features

Build static HTML files from Markdown files.
Use Plugins and Markdown Extensions to enhance MkDocs.
Use the built-in themes, third party themes or create your own.
Publish your documentation anywhere that static files can be served.
Much more!

Support

If you need help with MkDocs, do not hesitate to get in contact with us!

For questions and high-level discussions, use Discussions on GitHub.
- For small questions, a good alternative is the Chat room on Gitter/Matrix.
To report a bug or make a feature request, open an Issue on GitHub.

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.

Make sure to stick around to answer some questions as well!

Contributing to MkDocs

The MkDocs project welcomes, and depends on, contributions from developers and users in the open source community. Please see the Contributing Guide for information on how you can help.

Code of Conduct

Everyone interacting in the MkDocs project's codebases, issue trackers, and discussion forums is expected to follow the PyPA Code of Conduct.

License

BSD-2-Clause

mkdocs's People

Contributors

Stargazers

Watchers

Forkers

zeisss jkmacc awesome jpadilla svendowideit moveleft hernrup thiagomael the-jxc jspenc72 sampsyo mottosso garuda5 sbarysiuk jimpanic jimporter ericholscher edbrannin materkov piannelli hdngr vanzaj marccampbell f1nder alxxxla digaku javenfang erikzaadi d0ugal native2k esc24 frac javierjia econchick ryanneufeld michaeljoseph pieterlexis jpush dnrce earljon webromik haf tsenart fabiopiovam lu-chi dnephin idleberg craigez acxgit alihalabyah mlisbit robinandeer krnekhelesh sahilseth flyclops jeoygin hayd randomessence erichulser toilal mrmachine cxau fedelibre dannyben dbunskoek postpcera kqij2015 sriram-cliqr itech001 dporru major sankroh kaiix pombredanne lableorg samhatfield javedmehr ranlempow sjzabel durera blackli ci5er tmp-reg rusja davidmiller seanstory florianwolz jfmmovintracks ynov dustinfarris joshvillbrandt robertogerson rkday csakoda jinpro jmandala akademik saurajeet jamesbeebop alunduil

mkdocs's Issues

Rel links to css and js are invalid for subpages

Generated subpages expects css and js on same directory level though they are only existing in root.

Result: No css and js on anypage but index.

Version: 0.5

--clean switch

Allow mkdocs build --clean, which should remove all files/dirs inside the build directory except any hidden files/dirs (eg preserve .git in case it's a gh-pages repo)

Only allow this to be specified from the command line, not the config, for safety reasons.

generate redirect map to simplify moving documents around

this has always been a pain

Example Repo

I notice the mkdocs docs don't render with mkdocs. It would be great if there was an example repo to have something that mkdocs will build against.

Validate internal links

When internal links such as this are used in the documentation:

Please see the [project license](license.md) for further details.

The target of the internal link should be validated, and if it is not an included page in the docs an error should be raised.

As a further addition to this anchor links could also be validated against the corresponding table of contents.

bootstrap theme does not support responsive images

while the main theme does

Apply active class on nav bar items

theme_dir does not work

Copied the bootstrap theme to a themes dir in the root of my project. updated theme_dir to point to themes. Keep getting the following error.

jinja2.exceptions.TemplateNotFound: base.html

Nav

Use objects with .href, .children, .active properties, instead of just key: [name|children]

--config switch

Allow --config=other.yaml on the command line to use a config file other than mkdocs.yaml

generate a sitemap

i note there is a flag include_sitemap and a note that its not implemented yet.

Parse HTML into structure to allow templating

PDF support

Would be very nice to generate a pdf version of the
docs as well and add a link in the themes so that offline users may download a printable version.

Possibly using xhtml2pdf and a printable CSS style.

Tests for file operations

copy_file, write_file and copy_media_files need tests, but not sure best way to do so. Maybe use mock?

IRC Channel?

Should there be an official IRC channel, for development and support? It's generally easier than opening a new ticket :)

Parent pages

Pass a list of parent_pages into the context.
Use this in the readthedocs theme to populate breadcrumbs.

Should be an object with .title and .url

Add CLI option for output directory

It would be great to have an explicit option for where to output the doc HTML when mkdocs is run. This might be best implemented with a way of overriding any config file option from the CLI options generically.

Add Design Document

It would be great to know your vision for the project. There are a couple places in the tickets where you spell things out (not supporting autogeneration), but having those put in the docs so that people know the idea behind the project when they contribute would be great. I would like to contribute some code, but want to have a better feel for where you're going with it before I do :)

Search

Probably use Tipue.

If include_search is set needs to generate the compiled index javascript file.

Also if the theme includes a search.html page that should be rendered and included.

Configuration User-Guide contains latin gibberish

The configuration.md file contains latin gibberish, when explaining the site options.

https://github.com/tomchristie/mkdocs/blob/master/docs/user-guide/configuration.md#site_url

Code block scroll bars

I see that long lines in a code block will wrap, like this (Chrome on Mac):

instead of use horizontal scroll bars, like this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin eu urna fringilla, pellentesque mi in, rhoncus ipsum. Nullam est mauris, ornare sed hendrerit nec, rutrum in dui.

This may be just a preference, but I think scroll bars make code blocks easier to read. Is there a way to enable scroll bars, or is just how Python Markdown renders?

Modify theme

Wondering how to apply some additional CSS to a theme? Thanks

404 pages

If include_404 is set and the theme includes a 404.html page, then it should be rendered.

relpath issue with python 2.6

A link from the index page to a top level file:

[some file](local.md)

gets rendered as:

href="local.md" in python 2.7

but in python 2.6

href="../local.md"

I've traced this down to a change in posixpath.relpath called from nav.py

We are building a site on EC2 (Py 2.6 by default) and the ../ glitch results in effective urls like:

mysite.com//css/foo.css which S3 does not handle.

file transclusion

As an old Wiki-type, I'd love to only write some common things once - and I'd use transclusion...

I'm wondering if you'd be open to adding something like http://fletcher.github.io/MultiMarkdown-4/transclusion

Automatically Generate Navigation

The pages: section of mkdocs.yml allows for complete control over the navigation structure generated by mkdocs, but it'd be great if that wasn't necessary. For example, if I had the directory structure from your example page:

docs/
    index.md
    about.md
    license.md

That navigation items 'index', 'about', and 'license' could be auto-generated, so that each docs/ directory change didn't also have to be manually reflected in mkdocs.yml.

A further step would be to use the page_title: page metadata, or even an additional property.

The project daux.io does something like this, and it makes keeping the documentation organized and updated such a breeze.

Exit gracefully when misconfigured

Currently if mkdocs.yaml does not exist or if pages/project_name are not set, we'll exit with an exception. Really we should print a simple error to stderr and exit with an appropriate error code.

Option: parent homelink

In most cases you dont serve the documentation as a standalone website but it is instead linked from some other master site.

I suggest to include a config value in mkdocs.yml that, when set, renders a return link to the parent site in a, for the theme, appropriate location.

Add travis, coveralls & tox

See periodical for good example .travis.yml and tox.ini files.

Repo link only works in mkdocs theme

I'm about to fix this, what is the easiest way to run the local themes? python ./mkdocs/mkdocs serve doesn't show my changes for some reason.

Python 3 support

Are there any particular reasons not to write the lib for python3 instead?
We are integrating mkdocs in another suite and find it a little annoying to be stuck with python2.

Allow HTML pages.

Pages config currently only allows for markdown source files. Should also allow for HTML pages (which still get treated as Jinja2 templates), in order to eg. support custom homepages while still keeping the main docs pages as markdown.

Anchor links stradle nav bar in edge case.

Edge case: Anchor links that happen to just straddle the nav bar when the page is fully scrolled down will trigger the 'click to bottom' javascript code and will not be scrolled to the correct position. (See 1.0.0 anchor in screenshot)

Theme support

Hi @tomchristie , by the way thanks for lib!
Im having a wierd issue with serving anything but a default theme:

If I change config to

mkdocs.yml
site_name: 'Test doc'
theme: 'readthedocs'
#theme_dir: '/usr/lib64/python2.7/site-packages/mkdocs/themes' / tried but not working
pages:
- ['index.md', 'Home']


$mkdocs build
#OK , docs been build and correct theme is there 
$mkdocs serve
Traceback (most recent call last):
  File "/usr/bin/mkdocs", line 4, in <module>
    from mkdocs.build import build
ImportError: No module named mkdocs.build

This works with default theme.
Doesn't help if i make the change in mkdocs/config.py theme setting file or if i set it in mkdocs.yml . Anything but default theme throws ImportError.

Style issues and `$ is not defined` in readthedocs theme

Getting error in javascript console:

Uncaught ReferenceError: $ is not defined

And unordered/ordered lists and inline code spans seem to be missing styles.

mkdocs.yml:

site_name: Test readthedocs
theme: readthedocs

index.md:

This is an unordered list:

- Item 1
- Item 2
- Item 3

This is an ordered list:

1. Item 1
2. Item 2
3. Item 3

This `is an inline highlight`.

Screenshot:

Add getting started example.

In index.md the getting started should include a simple walkthrough of creating a two-page site.

misspelling or not ?

According to the config.py :
In order to run, mkdocs requires a single configuration file named mkdocs.yaml to exist in the current directory.

should be

In order to run, mkdocs requires a single configuration file named mkdocs.yml to exist in the current directory.

but then yaml files should have .yaml extension
http://www.yaml.org/faq.html
so the config.py is to blame and not the docs :)

generate a robots.txt

some defaults, and then hint at useful customisations

mkdocs build creates a site/.DS_Store

mkdocs build appears a to be creating a .DS_Store file in site

I installed it via pip, so the version is 0.9

ReadTheDocs theme responsive menu issue

The menu is responsive but the elements does not show on small screens. Button does absolutly nothing when pressed.

Support directory of md files without specifying them in the config

Is there a reason you have to specify each file in the config file to have it build? Seems like you could build all the files (perhaps having an exclude or include pattern), and pull the titles from the highest level header?

i18n support

It would be great to support multiple languages of documentation. Presumably using something like gettext.

Allow nav links with depth > 2

The default theme doesn't necessarily need to deal with styling them, but they should at least be allowed.

Themes

Use bootswatch themes as the built in defaults

http://bootswatch.com/

Also ideas for third party themes...

http://jacobian.org/writing/retiring-as-bdfls/
http://www.jsatt.com/
http://www.atmos.org/speaking.html
http://apidays.io/#home

generate or link to API docs

First, this is a very promising package! Thank you!

I would like to replace Sphinx with mkdocs, but Sphinx is able to autogenerate API docs from package docstrings. This would be very laborious to reproduce in mkdocs, I think, but perhaps mkdocs could easily link to existing html pages (API pages generated by Sphinx).

Apologies if this is trivial to do, and I just haven't figured it out yet.

Thanks again!