From 8e4b7e3e6283d0b79b23e1447e2b2f92f650b6df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Eustace?= <sebastien@eustace.io>
Date: Fri, 4 Jun 2021 16:38:09 +0200
Subject: [PATCH] Reorganize documentation

---
 .github/workflows/docs.yml                  |  29 ---
 docs/{docs/index.md => _index.md}           |  63 +++--
 docs/{docs => }/basic-usage.md              |  82 +++---
 docs/{docs => }/cli.md                      |  81 +++---
 docs/{docs => }/configuration.md            |  56 +++--
 docs/contributing.md                        | 266 ++++++++++++++++++++
 docs/{docs => }/dependency-specification.md |  27 +-
 docs/docs/contributing.md                   |   1 -
 docs/{docs => }/faq.md                      |  31 ++-
 docs/{docs => }/libraries.md                |  28 ++-
 docs/{docs => }/managing-environments.md    |  33 ++-
 docs/mkdocs.yml                             |  31 ---
 docs/{docs => }/plugins.md                  |  54 ++--
 docs/{docs => }/pyproject.md                | 101 ++++----
 docs/{docs => }/repositories.md             |  67 +++--
 docs/theme/main.html                        |  29 ---
 docs/theme/nav.html                         |  18 --
 docs/theme/toc.html                         |  10 -
 tox.ini                                     |  12 -
 19 files changed, 650 insertions(+), 369 deletions(-)
 delete mode 100644 .github/workflows/docs.yml
 rename docs/{docs/index.md => _index.md} (80%)
 rename docs/{docs => }/basic-usage.md (73%)
 rename docs/{docs => }/cli.md (89%)
 rename docs/{docs => }/configuration.md (81%)
 create mode 100644 docs/contributing.md
 rename docs/{docs => }/dependency-specification.md (93%)
 delete mode 100644 docs/docs/contributing.md
 rename docs/{docs => }/faq.md (78%)
 rename docs/{docs => }/libraries.md (78%)
 rename docs/{docs => }/managing-environments.md (86%)
 delete mode 100644 docs/mkdocs.yml
 rename docs/{docs => }/plugins.md (84%)
 rename docs/{docs => }/pyproject.md (78%)
 rename docs/{docs => }/repositories.md (76%)
 delete mode 100644 docs/theme/main.html
 delete mode 100644 docs/theme/nav.html
 delete mode 100644 docs/theme/toc.html

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
deleted file mode 100644
index b14884c8fa0..00000000000
--- a/.github/workflows/docs.yml
+++ /dev/null
@@ -1,29 +0,0 @@
-name: Documentation
-
-on:
-  push:
-    paths:
-      - 'docs/**'
-      - '.github/workflows/docs.yml'
-    branches:
-      - master
-  pull_request:
-    paths:
-      - 'docs/**'
-      - '.github/workflows/docs.yml'
-    branches:
-      - '**'
-
-jobs:
-  docs:
-    name: Documentation Build
-    runs-on: Ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: 3.8
-      - name: Install tox
-        run: pip install tox
-      - name: Build documentation
-        run: tox -e doc
diff --git a/docs/docs/index.md b/docs/_index.md
similarity index 80%
rename from docs/docs/index.md
rename to docs/_index.md
index 38d34317bad..d349033d651 100644
--- a/docs/docs/index.md
+++ b/docs/_index.md
@@ -1,6 +1,17 @@
+---
+title: "Introduction"
+draft: false
+type: docs
+layout: "single"
+
+menu:
+  docs:
+    weight: 0
+---
+
 # Introduction
 
-Poetry is a tool for dependency management and packaging in Python.
+Poetry is a tool for **dependency management** and **packaging** in Python.
 It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
 
 
@@ -9,11 +20,10 @@ It allows you to declare the libraries your project depends on and it will manag
 Poetry requires Python 2.7 or 3.5+. It is multi-platform and the goal is to make it work equally well
 on Windows, Linux and OSX.
 
-!!! note
-
-    Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2).
-    You should consider updating your Python version to a supported one.
-
+{{% note %}}
+Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2).
+You should consider updating your Python version to a supported one.
+{{% /note %}}
 
 ## Installation
 
@@ -29,10 +39,10 @@ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-
 (Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -
 ```
 
-!!!warning
-
-    The previous `get-poetry.py` installer is now deprecated, if you are currently using it
-    you should migrate to the new, supported, `install-poetry.py` installer.
+{{% warning %}}
+The previous `get-poetry.py` installer is now deprecated, if you are currently using it
+you should migrate to the new, supported, `install-poetry.py` installer.
+{{% /warning %}}
 
 The installer installs the `poetry` tool to Poetry's `bin` directory. This location depends on your system:
 
@@ -89,9 +99,9 @@ You can also install Poetry for a `git` repository by using the `--git` option:
 python install-poetry.py --git https://github.com/python-poetry/poetry.git@master
 ````
 
-!!!note
-
-    Note that the installer does not support Python < 3.6.
+{{% note %}}
+Note that the installer does not support Python < 3.6.
+{{% /note %}}
 
 
 ### Alternative installation methods
@@ -123,25 +133,24 @@ Using `pip` to install Poetry is possible.
 pip install --user poetry
 ```
 
-!!!warning
-
-    Be aware that it will also install Poetry's dependencies
-    which might cause conflicts with other packages.
-
+{{% warning %}}
+Be aware that it will also install Poetry's dependencies
+which might cause conflicts with other packages.
+{{% /warning %}}
 
 ## Updating `poetry`
 
 Updating Poetry to the latest stable version is as simple as calling the `self update` command.
 
-!!!warning
-
-    Poetry versions installed using the now deprecated `get-poetry.py` installer will not be able to use this
-    command to update to 1.2 releases or later. Migrate to using the `install-poetry.py` installer or `pipx`.
-
 ```bash
 poetry self update
 ```
 
+{{% warning %}}
+Poetry versions installed using the now deprecated `get-poetry.py` installer will not be able to use this
+command to update to 1.2 releases or later. Migrate to using the `install-poetry.py` installer or `pipx`.
+{{% /warning %}}
+
 If you want to install pre-release versions, you can use the `--preview` option.
 
 ```bash
@@ -187,9 +196,9 @@ poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
 
 ```
 
-!!! note
-
-    You may need to restart your shell in order for the changes to take effect.
+{{% note %}}
+You may need to restart your shell in order for the changes to take effect.
+{{% /note %}}
 
 For `zsh`, you must then add the following line in your `~/.zshrc` before `compinit`:
 
@@ -199,7 +208,7 @@ fpath+=~/.zfunc
 
 For `oh-my-zsh`, you must then enable poetry in your `~/.zshrc` plugins
 
-```
+```text
 plugins(
 	poetry
 	...
diff --git a/docs/docs/basic-usage.md b/docs/basic-usage.md
similarity index 73%
rename from docs/docs/basic-usage.md
rename to docs/basic-usage.md
index c9805bb3996..540bf8f237d 100644
--- a/docs/docs/basic-usage.md
+++ b/docs/basic-usage.md
@@ -1,7 +1,18 @@
+---
+title: "Basic usage"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 10
+---
+
 # Basic usage
 
 For the basic usage introduction we will be installing `pendulum`, a datetime library.
-If you have not yet installed Poetry, refer to the [Introduction](/docs/) chapter.
+If you have not yet installed Poetry, refer to the [Introduction]({{< relref "docs" >}} "Introduction") chapter.
 
 ## Project setup
 
@@ -77,8 +88,8 @@ It will automatically find a suitable version constraint **and install** the pac
 ## Using your virtual environment
 
 By default, poetry creates a virtual environment in `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
-You can change the [`cache-dir`](/docs/configuration/#cache-dir) value by editing the poetry config.
-Additionally, you can use the [`virtualenvs.in-project`](/docs/configuration/#virtualenvs.in-project) configuration variable
+You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache-dir configuration documentation") value by editing the poetry config.
+Additionally, you can use the [`virtualenvs.in-project`]({{< relref "configuration#virtualenvs.in-project" >}} "#virtualenvs.in-project configuration documentation") configuration variable
 to create virtual environment within your project directory.
 
 
@@ -96,18 +107,19 @@ The easiest way to activate the virtual environment is to create a new shell wit
 To deactivate the virtual environment and exit this new shell type `exit`.
 To deactivate the virtual environment without leaving the shell use `deactivate`.
 
-!!!note
+{{% note %}}
+**Why a new shell?**
 
-	**Why a new shell?**
-	Child processes inherit their environment from their parents, but do not share
-	them. As such, any modifications made by a child process, is not persisted after
-	the child process exits. A Python application (Poetry), being a child process,
-	cannot modify the environment of the shell that it has been called from such
-	that an activated virtual environment remains active after the Poetry command
-	has completed execution.
+Child processes inherit their environment from their parents, but do not share
+them. As such, any modifications made by a child process, is not persisted after
+the child process exits. A Python application (Poetry), being a child process,
+cannot modify the environment of the shell that it has been called from such
+that an activated virtual environment remains active after the Poetry command
+has completed execution.
 
-	Therefore, Poetry has to create a sub-shell with the virtual environment activated
-	in order for the subsequent commands to run from within the virtual environment.
+Therefore, Poetry has to create a sub-shell with the virtual environment activated
+in order for the subsequent commands to run from within the virtual environment.
+{{% /note %}}
 
 
 Alternatively, to avoid creating a new shell, you can manually activate the
@@ -116,11 +128,11 @@ To get the path to your virtual environment run `poetry env info --path`.
 You can also combine these into a nice one-liner, `source $(poetry env info --path)/bin/activate`
 To deactivate this virtual environment simply use `deactivate`.
 
-|                   | POSIX Shell                                       | Windows                                     | Exit/Deactivate |
-|-------------------|---------------------------------------------------|---------------------------------------------|-----------------|
-| New Shell         | `poetry shell`                                    | `poetry shell`                              | `exit`          |
-| Manual Activation | `source {path_to_venv}/bin/activate`              | `{path_to_venv}\Scripts\activate.bat`       | `deactivate`    |
-| One-liner         | ```source `poetry env info --path`/bin/activate```|                                             | `deactivate`    |
+|                   | POSIX Shell                                        | Windows                               | Exit/Deactivate |
+| ----------------- | -------------------------------------------------- | ------------------------------------- | --------------- |
+| New Shell         | `poetry shell`                                     | `poetry shell`                        | `exit`          |
+| Manual Activation | `source {path_to_venv}/bin/activate`               | `{path_to_venv}\Scripts\activate.bat` | `deactivate`    |
+| One-liner         | ```source `poetry env info --path`/bin/activate``` |                                       | `deactivate`    |
 
 
 ### Version constraints
@@ -128,21 +140,21 @@ To deactivate this virtual environment simply use `deactivate`.
 In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
 This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
 
-Please read [Dependency specification](/docs/dependency-specification) for more in-depth information on versions,
+Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on versions,
 how versions relate to each other, and on the different ways you can specify dependencies.
 
 
-!!!note
-
-    **How does Poetry download the right files?**
+{{% note %}}
+**How does Poetry download the right files?**
 
-    When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package
-    that you have requested and searches for it in any repository you have registered using the `repositories` key.
-    If you have not registered any extra repositories, or it does not find a package with that name in the
-    repositories you have specified, it falls back on PyPI.
+When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package
+that you have requested and searches for it in any repository you have registered using the `repositories` key.
+If you have not registered any extra repositories, or it does not find a package with that name in the
+repositories you have specified, it falls back on PyPI.
 
-    When Poetry finds the right package, it then attempts to find the best match
-    for the version constraint you have specified.
+When Poetry finds the right package, it then attempts to find the best match
+for the version constraint you have specified.
+{{% /note %}}
 
 
 ## Installing dependencies
@@ -189,9 +201,9 @@ Even if you develop alone, in six months when reinstalling the project you can f
 the dependencies installed are still working even if your dependencies released many new versions since then.
 (See note below about using the update command.)
 
-!!!note
-
-    For libraries it is not necessary to commit the lock file.
+{{% note %}}
+For libraries it is not necessary to commit the lock file.
+{{% /note %}}
 
 ### Installing dependencies only
 
@@ -212,7 +224,7 @@ This will fetch the latest matching versions (according to your `pyproject.toml`
 and update the lock file with the new versions.
 (This is equivalent to deleting the `poetry.lock` file and running `install` again.)
 
-!!!note
-
-    Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
-    are not synchronized.
+{{% note %}}
+Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
+are not synchronized.
+{{% /note %}}
diff --git a/docs/docs/cli.md b/docs/cli.md
similarity index 89%
rename from docs/docs/cli.md
rename to docs/cli.md
index 45881bec80a..0a1b8a265af 100644
--- a/docs/docs/cli.md
+++ b/docs/cli.md
@@ -1,3 +1,15 @@
+---
+title: "Commands"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 30
+---
+
+
 # Commands
 
 You've already learned how to use the command-line interface to do some things.
@@ -143,7 +155,7 @@ poetry install --remove-untracked
 ```
 
 You can also specify the extras you want installed
-by passing the `-E|--extras` option (See [Extras](/docs/pyproject/#extras) for more info)
+by passing the `-E|--extras` option (See [Extras]({{< relref "pyproject#extras" >}}) for more info)
 
 ```bash
 poetry install --extras "mysql pgsql"
@@ -159,7 +171,6 @@ Installing dependencies from lock file
 No dependencies to install or update
 
   - Installing <your-package-name> (x.x.x)
-
 ```
 
 If you want to skip this installation, use the `--no-root` option.
@@ -286,10 +297,10 @@ Alternatively, you can specify it in the `pyproject.toml` file. It means that ch
 my-package = {path = "../my/path", develop = true}
 ```
 
-!!!note
-
-    Before poetry 1.1 path dependencies were installed in editable mode by default. You should always set the `develop` attribute explicit,
-    to make sure the behavior is the same for all poetry versions.
+{{% note %}}
+Before poetry 1.1 path dependencies were installed in editable mode by default. You should always set the `develop` attribute explicit,
+to make sure the behavior is the same for all poetry versions.
+{{% /note %}}
 
 If the package(s) you want to install provide extras, you can specify them
 when adding the package:
@@ -409,7 +420,7 @@ poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]
 ````
 
 `setting-key` is a configuration option name and `setting-value1` is a configuration value.
-See [Configuration](/docs/configuration/) for all available settings.
+See [Configuration]({{< relref "configuration" >}}) for all available settings.
 
 ### Options
 
@@ -473,9 +484,9 @@ poetry search requests pendulum
 
 This command locks (without installing) the dependencies specified in `pyproject.toml`.
 
-!!!note
-
-     By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the `--no-update` option.
+{{% note %}}
+By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the `--no-update` option.
+{{% /note %}}
 
 ```bash
 poetry lock
@@ -497,17 +508,17 @@ The new version should ideally be a valid [semver](https://semver.org/) string o
 
 The table below illustrates the effect of these rules with concrete examples.
 
-| rule       |        before | after         |
-|------------|---------------|---------------|
-| major      |         1.3.0 | 2.0.0         |
-| minor      |         2.1.4 | 2.2.0         |
-| patch      |         4.1.1 | 4.1.2         |
-| premajor   |         1.0.2 | 2.0.0-alpha.0 |
-| preminor   |         1.0.2 | 1.1.0-alpha.0 |
-| prepatch   |         1.0.2 | 1.0.3-alpha.0 |
-| prerelease |         1.0.2 | 1.0.3-alpha.0 |
+| rule       | before        | after         |
+| ---------- | ------------- | ------------- |
+| major      | 1.3.0         | 2.0.0         |
+| minor      | 2.1.4         | 2.2.0         |
+| patch      | 4.1.1         | 4.1.2         |
+| premajor   | 1.0.2         | 2.0.0-alpha.0 |
+| preminor   | 1.0.2         | 1.1.0-alpha.0 |
+| prepatch   | 1.0.2         | 1.0.3-alpha.0 |
+| prerelease | 1.0.2         | 1.0.3-alpha.0 |
 | prerelease | 1.0.3-alpha.0 | 1.0.3-alpha.1 |
-| prerelease |  1.0.3-beta.0 | 1.0.3-beta.1  |
+| prerelease | 1.0.3-beta.0  | 1.0.3-beta.1  |
 
 ### Options
 
@@ -521,9 +532,9 @@ This command exports the lock file to other formats.
 poetry export -f requirements.txt --output requirements.txt
 ```
 
-!!!note
-
-    Only the `requirements.txt` format is currently supported.
+{{% note %}}
+Only the `requirements.txt` format is currently supported.
+{{% /note %}}
 
 ### Options
 
@@ -541,7 +552,7 @@ poetry export -f requirements.txt --output requirements.txt
 The `env` command regroups sub commands to interact with the virtualenvs
 associated with a specific project.
 
-See [Managing environments](/docs/managing-environments/) for more information about these commands.
+See [Managing environments]({{< relref "managing-environments" >}}) for more information about these commands.
 
 ## cache
 
@@ -628,18 +639,18 @@ For example, to add the `pypi-test` source, you can run:
 poetry source add pypi-test https://test.pypi.org/simple/
 ```
 
-!!!note
-
-    You cannot use the name `pypi` as it is reserved for use by the default PyPI source.
+{{% note %}}
+You cannot use the name `pypi` as it is reserved for use by the default PyPI source.
+{{% /note %}}
 
 #### Options
 
-* `--default`: Set this source as the [default](/docs/repositories/#disabling-the-pypi-repository) (disable PyPI).
-* `--secondary`: Set this source as a [secondary](/docs/repositories/#install-dependencies-from-a-private-repository) source.
+* `--default`: Set this source as the [default]({{< relref "repositories#disabling-the-pypi-repository" >}}) (disable PyPI).
+* `--secondary`: Set this source as a [secondary]({{< relref "repositories#install-dependencies-from-a-private-repository" >}}) source.
 
-!!!note
-
-    You cannot set a source as both `default` and `secondary`.
+{{% note %}}
+You cannot set a source as both `default` and `secondary`.
+{{% /note %}}
 
 ### `source show`
 
@@ -655,9 +666,9 @@ Optionally, you can show information of one or more sources by specifying their
 poetry source show pypi-test
 ```
 
-!!!note
-
-    This command will only show sources configured via the `pyproject.toml` and does not include PyPI.
+{{% note %}}
+This command will only show sources configured via the `pyproject.toml` and does not include PyPI.
+{{% /note %}}
 
 ### `source remove`
 
diff --git a/docs/docs/configuration.md b/docs/configuration.md
similarity index 81%
rename from docs/docs/configuration.md
rename to docs/configuration.md
index 4743515dd43..7b76b8da16a 100644
--- a/docs/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,6 +1,17 @@
+---
+title: "Configuration"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 40
+---
+
 # Configuration
 
-Poetry can be configured via the `config` command ([see more about its usage here](/docs/cli/#config))
+Poetry can be configured via the `config` command ([see more about its usage here]({{< relref "docs/cli#config" >}} "config command documentation"))
 or directly in the `config.toml` file that will be automatically be created when you first run that command.
 This file can typically be found in one of the following directories:
 
@@ -93,7 +104,9 @@ export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret
 
 ## Available settings
 
-### `cache-dir`: string
+### `cache-dir`
+
+**Type**: string
 
 The path to the cache directory used by Poetry.
 
@@ -108,23 +121,28 @@ Defaults to one of the following directories:
 Use parallel execution when using the new (`>=1.1.0`) installer.
 Defaults to `true`.
 
-!!!note:
-        This configuration will be ignored, and parallel execution disabled when running
-        Python 2.7 under Windows.
+{{% note %}}
+This configuration will be ignored, and parallel execution disabled when running
+Python 2.7 under Windows.
+{{% /note %}}
+
+### `virtualenvs.create`
 
-### `virtualenvs.create`: boolean
+**Type**: boolean
 
 Create a new virtual environment if one doesn't already exist.
 Defaults to `true`.
 
 If set to `false`, poetry will install dependencies into the current python environment.
 
-!!!note
+{{% note %}}
+When setting this configuration to `false`, the Python environment used must have `pip`
+installed and available.
+{{% /note %}}
 
-        When setting this configuration to `false`, the Python environment used must have `pip`
-        installed and available.
+### `virtualenvs.in-project`
 
-### `virtualenvs.in-project`: boolean
+**Type**: boolean
 
 Create the virtualenv inside the project's root directory.
 Defaults to `None`.
@@ -136,22 +154,30 @@ If not set explicitly (default), `poetry` will use the virtualenv from the `.ven
 directory when one is available. If set to `false`, `poetry` will ignore any
 existing `.venv` directory.
 
-### `virtualenvs.path`: string
+### `virtualenvs.path`
+
+**Type**: string
 
 Directory where virtual environments will be created.
 Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
 
-### `virtualenvs.options.always-copy`: boolean
+### `virtualenvs.options.always-copy`
+
+**Type**: boolean
 
 If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the venv. Thus all needed files are copied into the venv instead of symlinked.
 Defaults to `false`.
 
-### `virtualenvs.options.system-site-packages`: boolean
+### `virtualenvs.options.system-site-packages`
+
+**Type**: boolean
 
 Give the virtual environment access to the system site-packages directory.
 Applies on virtualenv creation.
 Defaults to `false`.
 
-### `repositories.<name>`: string
+### `repositories.<name>`
+
+**Type**: string
 
-Set a new alternative repository. See [Repositories](/docs/repositories/) for more information.
+Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information.
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 00000000000..d54359fde70
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,266 @@
+---
+title: "Contributing to Poetry"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 100
+---
+
+# Contributing to Poetry
+
+First off, thanks for taking the time to contribute!
+
+The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request.
+
+#### Table of contents
+
+[How to contribute](#how-to-contribute)
+
+  * [Reporting bugs](#reporting-bugs)
+  * [Suggesting enhancements](#suggesting-enhancements)
+  * [Contributing to documentation](#contributing-to-documentation)
+  * [Contributing to code](#contributing-to-code)
+  * [Issue triage](#issue-triage)
+  * [Git workflow](#git-workflow)
+
+
+## How to contribute
+
+### Reporting bugs
+
+This section guides you through submitting a bug report for Poetry.
+Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
+
+Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md), the information it asks helps the maintainers resolve the issue faster.
+
+> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
+
+#### Before submitting a bug report
+
+* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems.
+* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**.
+
+#### How do I submit a bug report?
+
+Bugs are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md).
+
+Explain the problem and include additional details to help maintainers reproduce the problem:
+
+* **Use a clear and descriptive title** for the issue to identify the problem.
+* **Describe the exact steps which reproduce the problem** in as many details as possible.
+* **Provide your pyproject.toml file** in a [Gist](https://gist.github.com) after removing potential private information (like private package repositories).
+* **Provide specific examples to demonstrate the steps to reproduce the issue**. Include links to files or GitHub projects, or copy-paste-able snippets, which you use in those examples.
+* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
+* **Explain which behavior you expected to see instead and why.**
+* **If the problem is an unexpected error being raised**, execute the corresponding command in **debug** mode (the `-vvv` option).
+
+Provide more context by answering these questions:
+
+* **Did the problem start happening recently** (e.g. after updating to a new version of Poetry) or was this always a problem?
+* If the problem started happening recently, **can you reproduce the problem in an older version of Poetry?** What's the most recent version in which the problem doesn't happen?
+* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
+
+Include details about your configuration and environment:
+
+* **Which version of Poetry are you using?** You can get the exact version by running `poetry -V` in your terminal.
+* **Which Python version Poetry has been installed for?** Execute the `debug:info` to get the information.
+* **What's the name and version of the OS you're using**?
+
+
+### Suggesting enhancements
+
+This section guides you through submitting an enhancement suggestion for Poetry, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
+
+Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---feature-request.md), including the steps that you imagine you would take if the feature you're requesting existed.
+
+#### Before submitting an enhancement suggestion
+
+* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems.
+* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**.
+
+#### How do I submit an Enhancement suggestion?
+
+Enhancement suggestions are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information:
+
+* **Use a clear and descriptive title** for the issue to identify the suggestion.
+* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
+* **Provide specific examples to demonstrate the steps**..
+* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
+
+### Contributing to documentation
+
+One of the simplest ways to get started contributing to a project is through improving documentation. Poetry is constantly evolving, this means that sometimes our documentation has gaps. You can help by
+adding missing sections, editing the existing content so it is more accessible or creating new content (tutorials, FAQs, etc).
+
+{{% note %}}
+A great way to understand Poetry's design and how it all fits together, is to add FAQ entries for commonly
+asked questions. Poetry members usually mark issues with [candidate/faq](https://github.com/python-poetry/poetry/issues?q=is%3Aissue+label%3Acandidate%2Ffaq+) to indicate that the issue either contains a response
+that explains how something works or might benefit from an entry in the FAQ.
+{{% /note %}}
+
+Issues pertaining to the documentation are usually marked with the [Documentation](https://github.com/python-poetry/poetry/labels/Documentation) label.
+
+### Contributing to code
+
+#### Picking an issue
+
+{{% note %}}
+If you are a first time contributor, and are looking for an issue to take on, you might want to look for [Good First Issue](https://github.com/python-poetry/poetry/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22)
+labelled issues. We do our best to label such issues, however we might fall behind at times. So, ask us.
+{{% /note %}}
+
+If you would like to take on an issue, feel free to comment on the issue tagging `@python-poetry/triage`. We are more than happy to discuss solutions on the issue. If you would like help with navigating
+the code base, join us on our [Discord Server](https://discordapp.com/invite/awxPgve).
+
+#### Local development
+
+You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://python-poetry.org/docs/#introduction) to start using Poetry.
+
+You will first need to clone the repository using `git` and place yourself in its directory:
+
+```bash
+$ git clone git@github.com:python-poetry/poetry.git
+$ cd poetry
+```
+
+{{% note %}}
+We recommend that you use a personal [fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) for this step. If you are new to GitHub collaboration,
+you can refer to the [Forking Projects Guide](https://guides.github.com/activities/forking/).
+{{% /note %}}
+
+Now, you will need to install the required dependency for Poetry and be sure that the current
+tests are passing on your machine:
+
+```bash
+$ poetry install
+$ poetry run pytest tests/
+```
+
+Poetry uses the [black](https://github.com/psf/black) coding style and you must ensure that your
+code follows it. If not, the CI will fail and your Pull Request will not be merged.
+
+Similarly, the import statements are sorted with [isort](https://github.com/timothycrosley/isort)
+and special care must be taken to respect it. If you don't, the CI will fail as well.
+
+To make sure that you don't accidentally commit code that does not follow the coding style, you can
+install a pre-commit hook that will check that everything is in order:
+
+```bash
+$ poetry run pre-commit install
+```
+
+You can also run it anytime using:
+
+```bash
+$ poetry run pre-commit run --all-files
+```
+
+Your code must always be accompanied by corresponding tests, if tests are not present your code
+will not be merged.
+
+#### Pull requests
+
+* Fill in [the required template](https://github.com/python-poetry/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
+* Be sure that your pull request contains tests that cover the changed or added code.
+* If your changes warrant a documentation change, the pull request must also update the documentation.
+
+{{% note %}}
+Make sure your branch is [rebased](https://docs.github.com/en/free-pro-team@latest/github/using-git/about-git-rebase) against the latest main branch. A maintainer might ask you to ensure the branch is
+up-to-date prior to merging your Pull Request if changes have conflicts.
+{{% /note %}}
+
+All pull requests, unless otherwise instructed, need to be first accepted into the main branch (`master`).
+
+### Issue triage
+
+{{% note %}}
+If you have an issue that hasn't had any attention, you can ping us `@python-poetry/triage` on the issue. Please, give us reasonable time to get to your issue first, spamming us with messages
+{{% /note %}}
+
+If you are helping with the triage of reported issues, this section provides some useful information to assist you in your contribution.
+
+#### Triage steps
+
+1. If `pyproject.toml` is missing or `-vvv` debug logs (with stack trace) is not provided and required, request that the issue author provides it.
+1. Attempt to reproduce the issue with the reported Poetry version or request further clarification from the issue author.
+1. Ensure the issue is not already resolved. You can attempt to reproduce using the latest preview release and/or poetry from the main branch.
+1. If the issue cannot be reproduced,
+   1. clarify with the issue's author,
+   1. close the issue or notify `@python-poetry/triage`.
+1. If the issue can be reproduced,
+   1. comment on the issue confirming so
+   1. notify `@python-poetry/triage`.
+   1. if possible, identify the root cause of the issue.
+   1. if interested, attempt to fix it via a pull request.
+
+#### Multiple versions
+
+Often times you would want to attempt to reproduce issues with multiple versions of `poetry` at the same time. For these use cases, the [pipx project](https://pipxproject.github.io/pipx/) is useful.
+
+You can set your environment up like so.
+
+```sh
+pipx install --suffix @1.0.10 'poetry==1.0.10'
+pipx install --suffix @1.1.0rc1 'poetry==1.1.0rc1'
+pipx install --suffix @master 'poetry @ git+https://github.com/python-poetry/poetry'
+```
+
+{{% note %}}
+Do not forget to update your `poetry@master` installation in sync with upstream.
+{{% /note %}}
+
+For `@local` it is recommended that you do something similar to the following as editable installs are not supported for PEP 517 projects.
+
+```sh
+# note this will not work for Windows, and we assume you have already run `poetry install`
+cd /path/to/python-poetry/poetry
+ln -sf $(poetry run which poetry) ~/.local/bin/poetry@local
+```
+
+{{% note %}}
+This mechanism can also be used to test pull requests.
+{{% /note %}}
+
+### Git Workflow
+
+All development work is performed against Poetry's main branch (`master`). All changes are expected to be submitted and accepted to this
+branch.
+
+#### Release branch
+
+When a release is ready, the following are required before a release is tagged.
+
+1. A release branch with the prefix `release-`, eg: `release-1.1.0rc1`.
+1. A pull request from the release branch to the main branch (`master`) if it's a minor or major release. Otherwise, to the bug fix branch (eg: `1.0`).
+   1. The pull request description MUST include the change log corresponding to the release (eg: [#2971](https://github.com/python-poetry/poetry/pull/2971)).
+   1. The pull request must contain a commit that updates [CHANGELOG.md](CHANGELOG.md) and bumps the project version (eg: [#2971](https://github.com/python-poetry/poetry/pull/2971/commits/824e7b79defca435cf1d765bb633030b71b9a780)).
+   1. The pull request must have the `Release` label specified.
+
+Once the branch pull-request is ready and approved, a member of `@python-poetry/core` will,
+
+1. Tag the branch with the version identifier (eg: `1.1.0rc1`).
+2. Merge the pull request once the release is created and assets are uploaded by the CI.
+
+{{% note %}}
+In this case, we prefer a merge commit instead of squash or rebase merge.
+{{% /note %}}
+
+#### Bug fix branch
+
+Once a minor version (eg: `1.1.0`) is released, a new branch for the minor version (eg: `1.1`) is created for the bug fix releases. Changes identified
+or acknowledged by the Poetry team as requiring a bug fix can be submitted as a pull requests against this branch.
+
+At the time of writing only issues meeting the following criteria may be accepted into a bug fix branch. Trivial fixes may be accepted on a
+case-by-case basis.
+
+1. The issue breaks a core functionality and/or is a critical regression.
+1. The change set does not introduce a new feature or changes an existing functionality.
+1. A new minor release is not expected within a reasonable time frame.
+1. If the issue affects the next minor/major release, a corresponding fix has been accepted into the main branch.
+
+{{% note %}}
+This is subject to the interpretation of a maintainer within the context of the issue.
+{{% /note %}}
diff --git a/docs/docs/dependency-specification.md b/docs/dependency-specification.md
similarity index 93%
rename from docs/docs/dependency-specification.md
rename to docs/dependency-specification.md
index 97888a02cd7..e2fa0e4e021 100644
--- a/docs/docs/dependency-specification.md
+++ b/docs/dependency-specification.md
@@ -1,3 +1,14 @@
+---
+title: "Dependency specification"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 70
+---
+
 # Dependency specification
 
 Dependencies for a project can be specified in various forms, which depend on the type
@@ -119,10 +130,10 @@ my-package = { path = "../my-package/", develop = false }
 my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
 ```
 
-!!!note
-
-    Before poetry 1.1 directory path dependencies were installed in editable mode by default. You should set the `develop` attribute explicitly,
-    to make sure the behavior is the same for all poetry versions.
+{{% note %}}
+Before poetry 1.1 directory path dependencies were installed in editable mode by default. You should set the `develop` attribute explicitly,
+to make sure the behavior is the same for all poetry versions.
+{{% /note %}}
 
 ## `url` dependencies
 
@@ -185,10 +196,10 @@ foo = [
 ]
 ```
 
-!!!note
-
-    The constraints **must** have different requirements (like `python`)
-    otherwise it will cause an error when resolving dependencies.
+{{% note %}}
+The constraints **must** have different requirements (like `python`)
+otherwise it will cause an error when resolving dependencies.
+{{% /note %}}
 
 ## Expanded dependency specification syntax
 
diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
deleted file mode 100644
index 568877b4a4f..00000000000
--- a/docs/docs/contributing.md
+++ /dev/null
@@ -1 +0,0 @@
-{!../CONTRIBUTING.md!}
diff --git a/docs/docs/faq.md b/docs/faq.md
similarity index 78%
rename from docs/docs/faq.md
rename to docs/faq.md
index 4d464d7ebc0..122a6856e6b 100644
--- a/docs/docs/faq.md
+++ b/docs/faq.md
@@ -1,6 +1,17 @@
+---
+title: "FAQ"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 110
+---
+
 # FAQ
 
-## Why is the dependency resolution process slow?
+### Why is the dependency resolution process slow?
 
 While the dependency resolver at the heart of Poetry is highly optimized and
 should be fast enough for most cases, sometimes, with some specific set of dependencies,
@@ -13,18 +24,18 @@ operation, both in bandwidth and time, which is why it seems this is a long proc
 
 At the moment there is no way around it.
 
-!!!note
-
-    Once Poetry has cached the releases' information, the dependency resolution process
-    will be much faster.
+{{% note %}}
+Once Poetry has cached the releases' information, the dependency resolution process
+will be much faster.
+{{% /note %}}
 
-## Why are unbound version constraints a bad idea?
+### Why are unbound version constraints a bad idea?
 
 A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency.
 This includes major versions breaking backward compatibility.
 
 Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC
-- you have to do a new release but the previous one stays broken.
+– you have to do a new release but the previous one stays broken.
 
 The only good alternative is to define an upper bound on your constraints,
 which you can increase in a new release after testing that your package is compatible
@@ -33,9 +44,9 @@ with the new major version of your dependency.
 For example instead of using `>=3.4` you should use `~3.4` which allows all versions `<4.0`.
 The `^` operator works very well with libraries following [semantic versioning](https://semver.org).
 
-## Is tox supported?
+### Is tox supported?
 
-Yes. By using the [isolated builds](https://tox.readthedocs.io/en/latest/config.html#conf-isolated_build) `tox` provides,
+**Yes**. By using the [isolated builds](https://tox.readthedocs.io/en/latest/config.html#conf-isolated_build) `tox` provides,
 you can use it in combination with the PEP 517 compliant build system provided by Poetry.
 
 So, in your `pyproject.toml` file, add this section if it does not already exist:
@@ -60,7 +71,7 @@ commands =
     poetry run pytest tests/
 ```
 
-## I don't want Poetry to manage my virtual environments. Can I disable it?
+### I don't want Poetry to manage my virtual environments. Can I disable it?
 
 While Poetry automatically creates virtual environments to always work isolated
 from the global Python installation, there are valid reasons why it's not necessary
diff --git a/docs/docs/libraries.md b/docs/libraries.md
similarity index 78%
rename from docs/docs/libraries.md
rename to docs/libraries.md
index db4822c342d..bd7d195bd6c 100644
--- a/docs/docs/libraries.md
+++ b/docs/libraries.md
@@ -1,3 +1,15 @@
+---
+title: "Libraries"
+draft: false
+type: docs
+layout: "docs"
+
+menu:
+  docs:
+    weight: 20
+---
+
+
 # Libraries
 
 This chapter will tell you how to make your library installable through Poetry.
@@ -9,7 +21,7 @@ While Poetry does not enforce any convention regarding package versioning,
 it **strongly** recommends to follow [semantic versioning](https://semver.org).
 
 This has many advantages for the end users and allows them to set appropriate
-[version constraints](/docs/dependency-specification/#version-constraints).
+[version constraints]({{< relref "dependency-specification#version-constraints" >}}).
 
 ## Lock file
 
@@ -49,14 +61,14 @@ poetry publish
 ```
 
 This will package and publish the library to PyPI, at the condition that you are a registered user
-and you have [configured your credentials](/docs/repositories/#adding-credentials) properly.
-
-!!!note
+and you have [configured your credentials]({{< relref "repositories#configuring-credentials" >}}) properly.
 
-    The `publish` command does not execute `build` by default.
+{{% note %}}
+The `publish` command does not execute `build` by default.
 
-    If you want to build and publish your packages together,
-    just pass the `--build` option.
+If you want to build and publish your packages together,
+just pass the `--build` option.
+{{% /note %}}
 
 Once this is done, your library will be available to anyone.
 
@@ -68,7 +80,7 @@ Sometimes, you may want to keep your library private but also being accessible t
 In this case, you will need to use a private repository.
 
 In order to publish to a private repository, you will need to add it to your
-global list of repositories. See [Adding a repository](/docs/repositories/#adding-a-repository)
+global list of repositories. See [Adding a repository]({{< relref "repositories#adding-a-repository" >}})
 for more information.
 
 Once this is done, you can actually publish to it like so:
diff --git a/docs/docs/managing-environments.md b/docs/managing-environments.md
similarity index 86%
rename from docs/docs/managing-environments.md
rename to docs/managing-environments.md
index 8b626cd813a..d9b728825a1 100644
--- a/docs/docs/managing-environments.md
+++ b/docs/managing-environments.md
@@ -1,3 +1,14 @@
+---
+title: "Managing environments"
+draft: false
+type: docs
+layout: "docs"
+
+menu:
+  docs:
+    weight: 60
+---
+
 # Managing environments
 
 Poetry makes project environment isolation one of its core features.
@@ -15,19 +26,19 @@ with the `python` requirement of the project. In this case, Poetry will try
 to find one that is and use it. If it's unable to do so then you will be prompted
 to activate one explicitly, see [Switching environments](#switching-between-environments).
 
-!!!note
-
-    To easily switch between Python versions, it is recommended to
-    use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
+{{% note %}}
+To easily switch between Python versions, it is recommended to
+use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
 
-    For instance, if your project is Python 2.7 only, a standard workflow
-    would be:
+For instance, if your project is Python 2.7 only, a standard workflow
+would be:
 
-    ```bash
-    pyenv install 2.7.15
-    pyenv local 2.7.15  # Activate Python 2.7 for the current project
-    poetry install
-    ```
+```bash
+pyenv install 2.7.15
+pyenv local 2.7.15  # Activate Python 2.7 for the current project
+poetry install
+```
+{{% /note %}}
 
 ## Switching between environments
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
deleted file mode 100644
index e055a6b6370..00000000000
--- a/docs/mkdocs.yml
+++ /dev/null
@@ -1,31 +0,0 @@
-site_name: Poetry documentation
-
-theme:
-  name: null
-  custom_dir: theme
-
-extra:
-  version: 2.0
-
-nav:
-  - Introduction: index.md
-  - Basic Usage: basic-usage.md
-  - Libraries: libraries.md
-  - Commands: cli.md
-  - Configuration: configuration.md
-  - Repositories: repositories.md
-  - Managing environments: managing-environments.md
-  - Dependency specification: dependency-specification.md
-  - Plugins: plugins.md
-  - The pyproject.toml file: pyproject.md
-  - Contributing: contributing.md
-  - FAQ: faq.md
-
-markdown_extensions:
-  - codehilite
-  - admonition
-  - pymdownx.superfences
-  - toc:
-      permalink: 
-  - markdown_include.include:
-      base_path: docs
diff --git a/docs/docs/plugins.md b/docs/plugins.md
similarity index 84%
rename from docs/docs/plugins.md
rename to docs/plugins.md
index f31bc85b3de..96ca48e191b 100644
--- a/docs/docs/plugins.md
+++ b/docs/plugins.md
@@ -1,3 +1,14 @@
+---
+title: "Plugins"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 80
+---
+
 # Plugins
 
 Poetry supports using and building plugins if you wish to
@@ -18,7 +29,7 @@ and may also depend on further packages.
 ### Plugin package
 
 The plugin package must depend on Poetry
-and declare a proper [plugin](/docs/pyproject/#plugins) in the `pyproject.toml` file.
+and declare a proper [plugin]({{< relref "pyproject#plugins" >}}) in the `pyproject.toml` file.
 
 ```toml
 [tool.poetry]
@@ -96,19 +107,19 @@ class MyApplicationPlugin(ApplicationPlugin):
         application.command_loader.register_factory("my-command", factory)
 ```
 
-!!!note
-
-    It's possible to do the following to register the command:
+{{% note %}}
+It's possible to do the following to register the command:
 
-    ```python
-    application.add(MyCommand())
-    ```
+```python
+application.add(MyCommand())
+```
 
-    However, it is **strongly** recommended to register a new factory
-    in the command loader to defer the loading of the command when it's actually
-    called.
+However, it is **strongly** recommended to register a new factory
+in the command loader to defer the loading of the command when it's actually
+called.
 
-    This will help keep the performances of Poetry good.
+This will help keep the performances of Poetry good.
+{{% /note %}}
 
 The plugin also must be declared in the `pyproject.toml` file of the plugin package
 as an `application.plugin` plugin:
@@ -118,9 +129,9 @@ as an `application.plugin` plugin:
 foo-command = "poetry_demo_plugin.plugin:MyApplicationPlugin"
 ```
 
-!!!warning
-
-    A plugin **must not** remove or modify in any way the core commands of Poetry.
+{{% warning %}}
+A plugin **must not** remove or modify in any way the core commands of Poetry.
+{{% /warning %}}
 
 
 ### Event handler
@@ -152,10 +163,15 @@ from poetry.plugins.application_plugin import ApplicationPlugin
 
 class MyApplicationPlugin(ApplicationPlugin):
     def activate(self, application: Application):
-        application.event_dispatcher.add_listener(COMMAND, self.load_dotenv)
+        application.event_dispatcher.add_listener(
+            COMMAND, self.load_dotenv
+        )
 
     def load_dotenv(
-        self, event: ConsoleCommandEvent, event_name: str, dispatcher: EventDispatcher
+        self,
+        event: ConsoleCommandEvent,
+        event_name: str,
+        dispatcher: EventDispatcher
     ) -> None:
         command = event.command
         if not isinstance(command, EnvCommand):
@@ -164,7 +180,9 @@ class MyApplicationPlugin(ApplicationPlugin):
         io = event.io
 
         if io.is_debug():
-            io.write_line("<debug>Loading environment variables.</debug>")
+            io.write_line(
+                "<debug>Loading environment variables.</debug>"
+            )
 
         load_dotenv()
 ```
@@ -188,7 +206,7 @@ The `plugin add` command will ensure that the plugin is compatible with the curr
 and install the needed packages for the plugin to work.
 
 The package specification formats supported by the `plugin add` command are the same as the ones supported
-by the [`add` command](/docs/cli/#add).
+by the [`add` command]({{< relref "cli#add" >}}).
 
 If you no longer need a plugin and want to uninstall it, you can use the `plugin remove` command.
 
diff --git a/docs/docs/pyproject.md b/docs/pyproject.md
similarity index 78%
rename from docs/docs/pyproject.md
rename to docs/pyproject.md
index 76cb2a86868..e102bffc104 100644
--- a/docs/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -1,3 +1,14 @@
+---
+title: "The pyproject.toml file"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 90
+---
+
 # The `pyproject.toml` file
 
 The `tool.poetry` section of the `pyproject.toml` file is composed of multiple sections.
@@ -40,9 +51,9 @@ The recommended notation for the most common licenses is (alphabetical):
 Optional, but it is highly recommended to supply this.
 More identifiers are listed at the [SPDX Open Source License Registry](https://spdx.org/licenses/).
 
-!!!note
-
-    If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`.
+{{% note %}}
+If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`.
+{{% /note %}}
 
 ## authors
 
@@ -91,11 +102,11 @@ classifiers = [
 ]
 ```
 
-!!!note
+{{% note %}}
+Note that Python classifiers are still automatically added for you and are determined by your `python` requirement.
 
-    Note that Python classifiers are still automatically added for you and are determined by your `python` requirement.
-
-    The `license` property will also set the License classifier automatically.
+The `license` property will also set the License classifier automatically.
+{{% /note %}}
 
 ## packages
 
@@ -137,26 +148,26 @@ packages = [
 
 From now on, only the `sdist` build archive will include the `my_other_package` package.
 
-!!!note
-
-    Using `packages` disables the package auto-detection feature meaning you have to
-    **explicitly** specify the "default" package.
+{{% note %}}
+Using `packages` disables the package auto-detection feature meaning you have to
+**explicitly** specify the "default" package.
 
-    For instance, if you have a package named `my_package` and you want to also include
-    another package named `extra_package`, you will need to specify `my_package` explicitly:
+For instance, if you have a package named `my_package` and you want to also include
+another package named `extra_package`, you will need to specify `my_package` explicitly:
 
-    ```toml
-    packages = [
-        { include = "my_package" },
-        { include = "extra_package" },
-    ]
-    ```
-
-!!!note
+```toml
+packages = [
+    { include = "my_package" },
+    { include = "extra_package" },
+]
+```
+{{% /note %}}
 
-    Poetry is clever enough to detect Python subpackages.
+{{% note %}}
+Poetry is clever enough to detect Python subpackages.
 
-    Thus, you only have to specify the directory where your root package resides.
+Thus, you only have to specify the directory where your root package resides.
+{{% /note %}}
 
 ## include and exclude
 
@@ -208,15 +219,15 @@ name = 'private'
 url = 'http://example.com/simple'
 ```
 
-!!!note
-
-    Be aware that declaring the python version for which your package
-    is compatible is mandatory:
+{{% note %}}
+Be aware that declaring the python version for which your package
+is compatible is mandatory:
 
-    ```toml
-    [tool.poetry.dependencies]
-    python = "^3.6"
-    ```
+```toml
+[tool.poetry.dependencies]
+python = "^3.6"
+```
+{{% /note %}}
 
 ## `scripts`
 
@@ -229,9 +240,9 @@ poetry = 'poetry.console:run'
 
 Here, we will have the `poetry` script installed which will execute `console.run` in the `poetry` package.
 
-!!!note
-
-    When a script is added or updated, run `poetry install` to make them available in the project's virtualenv.
+{{% note %}}
+When a script is added or updated, run `poetry install` to make them available in the project's virtualenv.
+{{% /note %}}
 
 ## `extras`
 
@@ -276,10 +287,11 @@ the `databases` extra can be installed as shown below.
 pip install awesome[databases]
 ```
 
-!!!note
+{{% note %}}
+The dependencies specified for each `extra` must already be defined as project dependencies.
 
-    The dependencies specified for each `extra` must already be defined as project dependencies.
-    Dependencies listed in the `dev-dependencies` section cannot be specified as extras.
+Dependencies listed in the `dev-dependencies` section cannot be specified as extras.
+{{% /note %}}
 
 
 ## `plugins`
@@ -322,12 +334,11 @@ requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"
 ```
 
-!!!note
-
-    When using the `new` or `init` command this section will be automatically added.
-
-
-!!!note
+{{% note %}}
+When using the `new` or `init` command this section will be automatically added.
+{{% /note %}}
 
-    If your `pyproject.toml` file still references `poetry` directly as a build backend,
-    you should update it to reference `poetry-core` instead.
+{{% note %}}
+If your `pyproject.toml` file still references `poetry` directly as a build backend,
+you should update it to reference `poetry-core` instead.
+{{% /note %}}
diff --git a/docs/docs/repositories.md b/docs/repositories.md
similarity index 76%
rename from docs/docs/repositories.md
rename to docs/repositories.md
index 952e91f15d4..5b253e023c0 100644
--- a/docs/docs/repositories.md
+++ b/docs/repositories.md
@@ -1,3 +1,14 @@
+---
+title: "Repositories"
+draft: false
+type: docs
+layout: "docs"
+
+menu:
+  docs:
+    weight: 50
+---
+
 # Repositories
 
 ## Using the PyPI repository
@@ -37,24 +48,25 @@ poetry config http-basic.foo username password
 
 If you do not specify the password you will be prompted to write it.
 
-!!!note
+{{% note %}}
+To publish to PyPI, you can set your credentials for the repository named `pypi`.
 
-    To publish to PyPI, you can set your credentials for the repository named `pypi`.
+Note that it is recommended to use [API tokens](https://pypi.org/help/#apitoken)
+when uploading packages to PyPI.
+Once you have created a new token, you can tell Poetry to use it:
 
-    Note that it is recommended to use [API tokens](https://pypi.org/help/#apitoken)
-    when uploading packages to PyPI.
-    Once you have created a new token, you can tell Poetry to use it:
+```bash
+poetry config pypi-token.pypi my-token
+```
 
-    ```bash
-    poetry config pypi-token.pypi my-token
-    ```
+If you still want to use your username and password, you can do so with the following
+call to `config`.
 
-    If you still want to use your username and password, you can do so with the following
-    call to `config`.
+```bash
+poetry config http-basic.pypi username password
+```
+{{% /note %}}
 
-    ```bash
-    poetry config http-basic.pypi username password
-    ```
 
 You can also specify the username and password when using the `publish` command
 with the `--username` and `--password` options.
@@ -71,7 +83,7 @@ export POETRY_HTTP_BASIC_PYPI_USERNAME=username
 export POETRY_HTTP_BASIC_PYPI_PASSWORD=password
 ```
 
-See [Using environment variables](/docs/configuration/#using-environment-variables) for more information
+See [Using environment variables]({{< relref "configuration#using-environment-variables" >}}) for more information
 on how to configure Poetry with environment variables.
 
 #### Custom certificate authority and mutual TLS authentication
@@ -79,9 +91,10 @@ Poetry supports repositories that are secured by a custom certificate authority
 certificate-based client authentication.  The following will configure the "foo" repository to validate the repository's
 certificate using a custom certificate authority and use a client certificate (note that these config variables do not
 both need to be set):
+
 ```bash
-    poetry config certificates.foo.cert /path/to/ca.pem
-    poetry config certificates.foo.client-cert /path/to/client.pem
+poetry config certificates.foo.cert /path/to/ca.pem
+poetry config certificates.foo.client-cert /path/to/client.pem
 ```
 
 ### Install dependencies from a private repository
@@ -99,19 +112,19 @@ url = "https://foo.bar/simple/"
 
 From now on, Poetry will also look for packages in your private repository.
 
-!!!note
+{{% note %}}
+Any custom repository will have precedence over PyPI.
 
-    Any custom repository will have precedence over PyPI.
+If you still want PyPI to be your primary source for your packages
+you can declare custom repositories as secondary.
 
-    If you still want PyPI to be your primary source for your packages
-    you can declare custom repositories as secondary.
-
-    ```toml
-    [[tool.poetry.source]]
-    name = "foo"
-    url = "https://foo.bar/simple/"
-    secondary = true
-    ```
+```toml
+[[tool.poetry.source]]
+name = "foo"
+url = "https://foo.bar/simple/"
+secondary = true
+```
+{{% /note %}}
 
 If your private repository requires HTTP Basic Auth be sure to add the username and
 password to your `http-basic` configuration using the example above (be sure to use the
diff --git a/docs/theme/main.html b/docs/theme/main.html
deleted file mode 100644
index 83151151ff6..00000000000
--- a/docs/theme/main.html
+++ /dev/null
@@ -1,29 +0,0 @@
----
-layout: documentation
-title: {{ page.title|striptags|e }}
----
-
-    <section class="p-b-50 p-t-50 documentation-content">
-        <div class="container">
-            <div class="panel panel-transparent">
-                <div class="row p-l-20 p-r-20 p-b-20 p-t-5 xs-no-padding">
-                    <div class="row">
-                        <div class="col-md-3 documentation-toc">
-                            <ul class="current">
-                                {% set navlevel = 1 %}
-
-                                {% for nav_item in nav %}
-                                <li class="toctree-l{{ navlevel }}{% if nav_item.active and not nav_item.children %} current{%endif%}">
-                                    {% include 'nav.html' %}
-                                </li>
-                                {% endfor %}
-                            </ul>
-                        </div>
-                        <div class="col-md-9 documentation-body">
-                            {{page.content}}
-                        </div>
-                    </div>
-                </div>
-            </div>
-        </div>
-    </section>
diff --git a/docs/theme/nav.html b/docs/theme/nav.html
deleted file mode 100644
index e9d2b383844..00000000000
--- a/docs/theme/nav.html
+++ /dev/null
@@ -1,18 +0,0 @@
-<a class="{% if nav_item.active%}current{%endif%}" href="{{ base_url }}/{{ nav_item.url }}">{{ nav_item.title }}</a>
-
-{%- if nav_item == page or nav_item.children %}
-<ul class="subnav">
-    {%- if nav_item == page %}
-    {% include 'toc.html' %}
-    {%- endif %}
-    {%- if nav_item.children %}
-    {%- set navlevel = navlevel + 1%}
-    {%- for nav_item in nav_item.children %}
-    <li class="{% if navlevel > 2 %}toctree-l{{ navlevel }}{% endif %}{% if nav_item.active%} current{%endif%}">
-        {% include 'nav.html' %}
-    </li>
-    {%- endfor %}
-    {%- set navlevel = navlevel - 1%}
-    {%- endif %}
-</ul>
-{%- endif %}
diff --git a/docs/theme/toc.html b/docs/theme/toc.html
deleted file mode 100644
index 4f3e8e09ab6..00000000000
--- a/docs/theme/toc.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{% for toc_item in page.toc %}
-<!--<li class="toctree-l{{ navlevel + 1 }}"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>-->
-{% if toc_item.children %}
-<ul>
-    {% for toc_item in toc_item.children %}
-    <li><a class="toctree-l{{ navlevel + 2 }}" href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
-    {% endfor %}
-</ul>
-{% endif %}
-{% endfor %}
diff --git a/tox.ini b/tox.ini
index 722c0e1adf1..6e40e8b7f8a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -8,15 +8,3 @@ whitelist_externals = poetry
 commands =
     poetry install -vv --no-root
     poetry run pytest {posargs} tests/
-
-[testenv:doc]
-whitelist_externals =
-skip_install = true
-deps =
-    markdown-include
-    mkdocs
-    pygments
-    pygments-github-lexers
-    pymdown-extensions
-commands =
-    mkdocs build -f docs/mkdocs.yml