Commit 48f7b16f authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files

Use a new MkDocs site

parent 4536498c
image: python:alpine
before_script:
- pip install mkdocs
# Add your custom theme if not inside a theme_dir
# (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
# - pip install mkdocs-material
pages:
script:
- mkdocs build
- mv site public
artifacts:
paths:
- public
only:
- master
# Example [MkDocs](http://mkdocs.org/) website using GitLab Pages.
![Build Status](https://gitlab.com/pages/mkdocs/badges/master/build.svg)
---
Example [MkDocs] website using GitLab Pages.
Learn more about GitLab Pages at https://pages.gitlab.io and the official
documentation http://doc.gitlab.com/ee/pages/README.html.
documentation https://docs.gitlab.com/ce/user/project/pages/.
---
## GitLab CI
......@@ -13,7 +19,8 @@ image: python:alpine
before_script:
- pip install mkdocs
# add your custom theme (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) if not inside a theme_dir
## Add your custom theme if not inside a theme_dir
## (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
# - pip install mkdocs-material
pages:
......@@ -32,17 +39,13 @@ pages:
To work locally with this project, you'll have to follow the steps below:
1. Fork, clone or download this project
1. [Install](http://www.mkdocs.org/#installation) MkDocs
1. Preview your project: `mkdocs serve`
1. [Install][] MkDocs
1. Preview your project: `mkdocs serve`,
your site can be accessed under `localhost:8000`
1. Add content
1. Generate the website: `mkdocs build` (optional)
Read more at MkDocs's [documentation](http://www.mkdocs.org/).
### Preview your site
If you clone or download this project to your local computer and run `mkdocs serve`,
your site can be accessed under `localhost:8000`.
Read more at MkDocs [documentation][].
## GitLab User or Group Pages
......@@ -52,6 +55,32 @@ your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
You'll need to configure your site too: change this line
in your `mkdocs.yml`, from `"https://pages.gitlab.io/hugo/"` to `site_url = "https://namespace.gitlab.io"`.
in your `mkdocs.yml`, from `"https://pages.gitlab.io/hugo/"` to
`site_url = "https://namespace.gitlab.io"`.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
## Troubleshooting
1. CSS is missing! That means two things:
Either that you have wrongly set up the CSS URL in your templates, or
your static generator has a configuration option that needs to be explicitly
set in order to serve static assets under a relative URL.
[ci]: https://about.gitlab.com/gitlab-ci/
[mkdocs]: http://www.mkdocs.org
[install]: http://www.mkdocs.org/#installation
[documentation]: http://www.mkdocs.org
[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
---
Read more about [user/group Pages][userpages] and [project Pages][projpages].
\ No newline at end of file
Forked from https://gitlab.com/morph027/mkdocs
www.mkdocs.org
# Contributing to MkDocs
An introduction to contributing to the MkDocs project.
The MkDocs project welcomes, and depends, on contributions from developers and
users in the open source community. Contributions can be made in a number of
ways, a few examples are:
- Code patches via pull requests
- Documentation improvements
- Bug reports and patch reviews
## Code of Conduct
Everyone interacting in the MkDocs project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
## Reporting an Issue
Please include as much detail as you can. Let us know your platform and MkDocs
version. If the problem is visual (for example a theme or design issue) please
add a screenshot and if you get an error please include the full error and
traceback.
## Testing the Development Version
If you want to just install and try out the latest development version of
MkDocs you can do so with the following command. This can be useful if you
want to provide feedback for a new feature or want to confirm if a bug you
have encountered is fixed in the git master. It is **strongly** recommended
that you do this within a [virtualenv].
```bash
pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz
```
## Installing for Development
First you'll need to fork and clone the repository. Once you have a local
copy, run the following command. It is **strongly** recommended that you do
this within a [virtualenv].
```bash
pip install --editable .
```
This will install MkDocs in development mode which binds the `mkdocs` command
to the git repository.
## Running the tests
To run the tests, it is recommended that you use [Tox]. This just needs
to be pip installed and then the test suite can be ran for MkDocs but running
the command `tox` in the root of your MkDocs repository.
It will attempt to run the tests against all of the Python versions we
support. So don't be concerned if you are missing some and they fail. The rest
will be verified by [Travis] when you submit a pull request.
## Submitting Pull Requests
Once you are happy with your changes or you are ready for some feedback, push
it to your fork and send a pull request. For a change to be accepted it will
most likely need to have tests and documentation if it is a new feature.
[virtualenv]: https://virtualenv.pypa.io/en/latest/userguide.html
[tox]: https://tox.readthedocs.io/en/latest/
[travis]: https://travis-ci.org/repositories
[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
# License
The legal stuff.
---
## Included projects
Themes used under license from the ReadTheDocs projects.
* ReadTheDocs theme - [View license](https://github.com/snide/sphinx_rtd_theme/blob/master/LICENSE).
Many thanks to the authors and contributors of those wonderful projects.
## MkDocs License (BSD)
Copyright © 2014, Tom Christie. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer. Redistributions in binary form must
reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This diff is collapsed.
div.col-md-9 h1:first-of-type {
text-align: center;
font-size: 60px;
font-weight: 300;
}
div.col-md-9 p:first-of-type {
text-align: center;
}
div.col-md-9 p.admonition-title:first-of-type {
text-align: left;
}
div.col-md-9 h1:first-of-type .headerlink {
display: none;
}
code.no-highlight {
color: black;
}
# MkDocs
# Welcome to MkDocs
Project documentation with Markdown.
This is a test site hosted on [GitLab Pages](https://pages.gitlab.io). You can
[browse its source code](https://gitlab.com/pages/mkdocs), fork it and start
using it on your projects.
---
For full documentation visit [mkdocs.org](http://mkdocs.org).
!!! Note
This site was built with GitLab Pages!.
## Commands
Visit this project at [https://gitlab.com/pages/mkdocs](https://gitlab.com/pages/mkdocs).
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs help` - Print this help message.
## Overview
## Project layout
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.
### Host anywhere
MkDocs builds completely static HTML sites that you can host on GitHub pages,
Amazon S3, or [anywhere][deploy] else you choose.
### Great themes available
There's a stack of good looking themes available for MkDocs. Choose between
the built in themes: [mkdocs] and [readthedocs], select one of the 3rd
party themes in the [MkDocs wiki], or [build your own].
### Preview your site as you work
The built-in dev-server allows you to preview your documentation as you're
writing it. It will even auto-reload and refresh your browser whenever you save
your changes.
### Easy to customize
Get your project documentation looking just the way you want it by customizing
the theme.
---
## Installation
### Install with a Package Manager
If you have and use a package manager (such as [apt-get], [dnf], [homebrew],
[yum], [chocolatey], etc.) to install packages on your system, then you may
want to search for a "MkDocs" package and, if a recent version is available,
install it with your package manager (check your system's documentation for
details). That's it, you're done! Skip down to [Getting Started](#getting-started).
If your package manager does not have a recent "MkDocs" package, you can still
use your package manager to install "Python" and "pip". Then you can use pip to
[install MkDocs](#installing-mkdocs).
[apt-get]: https://help.ubuntu.com/community/AptGet/Howto
[homebrew]: http://brew.sh/
[dnf]: http://dnf.readthedocs.io/en/latest/index.html
[yum]: http://yum.baseurl.org/
[chocolatey]: https://chocolatey.org/
### Manual Installation
In order to manually install MkDocs you'll need [Python] installed on your
system, as well as the Python package manager, [pip]. You can check if you have
these already installed from the command line:
```bash
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
```
MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.
#### Installing Python
Install [Python] by downloading an installer appropriate for your system from
[python.org] and running it.
!!! Note
If you are installing Python on Windows, be sure to check the box to have
Python added to your PATH if the installer offers such an option (it's
normally off by default).
![Add Python to PATH](img/win-py-install.png)
[python.org]: https://www.python.org/downloads/
#### Installing pip
If you're using a recent version of Python, the Python package manager, [pip],
is most likely installed by default. However, you may need to upgrade pip to the
lasted version:
```bash
pip install --upgrade pip
```
If you need to install [pip] for the first time, download [get-pip.py].
Then run the following command to install it:
```bash
python get-pip.py
```
#### Installing MkDocs
Install the `mkdocs` package using pip:
```bash
pip install mkdocs
```
You should now have the `mkdocs` command installed on your system. Run `mkdocs
--version` to check that everything worked okay.
```bash
$ mkdocs --version
mkdocs, version 0.15.3
```
!!! Note
If you are using Windows, some of the above commands may not work
out-of-the-box.
A quick solution may be to preface every Python command with `python -m`
like this:
python -m pip install mkdocs
python -m mkdocs
For a more permanent solution, you may need to edit your `PATH` environment
variable to include the `Scripts` directory of your Python installation.
Recent versions of Python include a script to do this for you. Navigate to
your Python installation directory (for example `C:\Python34\`), open the
`Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double
clicking on it. Alternatively, you can [download][a2p] the script and run it
(`python win_add2path.py`).
[a2p]: https://svn.python.org/projects/python/trunk/Tools/scripts/win_add2path.py
---
## Getting Started
Getting started is super easy.
```bash
mkdocs new my-project
cd my-project
```
Take a moment to review the initial project that has been created for you.
![The initial MkDocs layout](img/initial-layout.png)
There's a single configuration file named `mkdocs.yml`, and a folder named
`docs` that will contain your documentation source files. Right now the `docs`
folder just contains a single documentation page, named `index.md`.
MkDocs comes with a built-in dev-server that lets you preview your documentation
as you work on it. Make sure you're in the same directory as the `mkdocs.yml`
configuration file, and then start the server by running the `mkdocs serve`
command:
```bash
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes
```
Open up `http://127.0.0.1:8000/` in your browser, and you'll see the default
home page being displayed:
![The MkDocs live server](img/screenshot.png)
The dev-server also supports auto-reloading, and will rebuild your documentation
whenever anything in the configuration file, documentation directory, or theme
directory changes.
Open the `docs/index.md` document in your text editor of choice, change the
initial heading to `MkLorum`, and save your changes. Your browser will
auto-reload and you should see your updated documentation immediately.
Now try editing the configuration file: `mkdocs.yml`. Change the
[`site_name`][site_name] setting to `MkLorum` and save the file.
```yaml
site_name: MkLorum
```
Your browser should immediately reload, and you'll see your new site name take
effect.
![The site_name setting](img/site-name.png)
## Adding pages
Now add a second page to your documentation:
```bash
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
```
As our documentation site will include some navigation headers, you may want to
edit the configuration file and add some information about the order, title, and
nesting of each page in the navigation header by adding a [`pages`][pages]
setting:
```yaml
site_name: MkLorum
pages:
- Home: index.md
- About: about.md
```
Save your changes and you'll now see a navigation bar with `Home` and `About`
items on the left as well as `Search`, `Previous`, and `Next` items on the
right.
![Screenshot](img/multipage.png)
Try the menu items and navigate back and forth between pages. Then click on
`Search`. A search dialog will appear, allowing you to search for any text on
any page. Notice that the search results include every occurrence of the search
term on the site and links directly to the section of the page in which the
search term appears. You get of all that with no effort or configuration on your
part!
![Screenshot](img/search.png)
## Theming our documentation
Now change the configuration file to alter how the documentation is displayed by
changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting:
```yaml
site_name: MkLorum
pages:
- Home: index.md
- About: about.md
theme: readthedocs
```
Save your changes, and you'll see the ReadTheDocs theme being used.
![Screenshot](img/readthedocs.png)
## Changing the Favicon Icon
By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create
an `img` subdirectory in your `docs_dir` and copy your custom `favicon.ico` file
to that directory. MkDocs will automaticaly detect and use that file as your
favicon icon.
[MkDocs favicon]: /img/favicon.ico
## Building the site
That's looking good. You're ready to deploy the first pass of your `MkLorum`
documentation. First build the documentation:
```bash
mkdocs build
```
This will create a new directory, named `site`. Take a look inside the
directory:
```bash
$ ls site
about fonts index.html license search.html
css img js mkdocs sitemap.xml
```
Notice that your source documentation has been output as two HTML files named
`index.html` and `about/index.html`. You also have various other media that's
been copied into the `site` directory as part of the documentation theme. You
even have a `sitemap.xml` file and `mkdocs/search_index.json`.
If you're using source code control such as `git` you probably don't want to
check your documentation builds into the repository. Add a line containing
`site/` to your `.gitignore` file.
```bash
echo "site/" >> .gitignore
```
If you're using another source code control tool you'll want to check it's
documentation on how to ignore specific directories.
After some time, files may be removed from the documentation but they will still
reside in the `site` directory. To remove those stale files, just run `mkdocs`
with the `--clean` switch.
```bash
mkdocs build --clean
```
## Other Commands and Options
There are various other commands and options available. For a complete list of
commands, use the `--help` flag:
```bash
mkdocs --help
```
To view a list of options available on a given command, use the `--help` flag
with that command. For example, to get a list of all options available for the
`build` command run the following:
```bash
mkdocs build --help
```
## Deploying
The documentation site that you just built only uses static files so you'll be
able to host it from pretty much anywhere. [GitHub project pages] and [Amazon
S3] may be good hosting options, depending upon your needs. Upload the contents
of the entire `site` directory to wherever you're hosting your website from and
you're done. For specific instructions on a number of common hosts, see the
[Deploying your Docs][deploy] page.
## Getting help
To get help with MkDocs, please use the [discussion group], [GitHub issues] or
the MkDocs IRC channel `#mkdocs` on freenode.
[deploy]: user-guide/deploying-your-docs/
[mkdocs]: user-guide/styling-your-docs/#mkdocs
[readthedocs]: user-guide/styling-your-docs/#readthedocs
[MkDocs wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
[build your own]: user-guide/custom-themes/
[Amazon S3]: http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html
[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
[pages]: user-guide/configuration/#pages
[discussion group]: https://groups.google.com/forum/#!forum/mkdocs
[GitHub issues]: https://github.com/mkdocs/mkdocs/issues
[GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually/
[pip]: http://pip.readthedocs.io/en/stable/installing/
[Python]: https://www.python.org/
[site_name]: user-guide/configuration/#site_name
[theme]: user-guide/configuration/#theme
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
# Configuration
Guide to all available configuration settings.
---
## Introduction
Project settings are always configured by using a YAML configuration file in the
project directory named `mkdocs.yml`.
As a minimum this configuration file must contain the `site_name` setting. All
other settings are optional.
## Project information
### site_name
This is a **required setting**, and should be a string that is used as the main
title for the project documentation. For example:
```yaml
site_name: Marshmallow Generator
```