From 1a5c349fa7db972d645983aa79d6435d54328693 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 00:16:43 +0200
Subject: [PATCH 01/12] Move to markdown.

---
 .pre-commit-config.yaml                       | 28 ++++++++++---
 README.md                                     | 40 +++++++++++++++++++
 docs/rtd_environment.yml                      |  1 +
 docs/source/{api.rst => api.md}               | 15 +++----
 docs/source/changes.md                        | 21 ++++++++++
 docs/source/changes.rst                       | 27 -------------
 docs/source/conf.py                           | 12 +++++-
 docs/source/index.md                          | 17 ++++++++
 docs/source/index.rst                         | 12 ------
 environment.yml                               |  1 +
 .../docs/rtd_environment.yml                  |  1 +
 .../docs/source/{api.rst => api.md}           | 13 +++---
 .../docs/source/{changes.rst => changes.md}   |  7 +---
 .../docs/source/conf.py                       | 19 +++++----
 .../docs/source/index.md                      | 10 +++++
 .../docs/source/index.rst                     |  9 -----
 {{cookiecutter.project_slug}}/environment.yml |  1 +
 17 files changed, 154 insertions(+), 80 deletions(-)
 create mode 100644 README.md
 rename docs/source/{api.rst => api.md} (51%)
 create mode 100644 docs/source/changes.md
 delete mode 100644 docs/source/changes.rst
 create mode 100644 docs/source/index.md
 delete mode 100644 docs/source/index.rst
 rename {{cookiecutter.project_slug}}/docs/source/{api.rst => api.md} (55%)
 rename {{cookiecutter.project_slug}}/docs/source/{changes.rst => changes.md} (63%)
 create mode 100644 {{cookiecutter.project_slug}}/docs/source/index.md
 delete mode 100644 {{cookiecutter.project_slug}}/docs/source/index.rst

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 714e51a..f1aba5e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -45,11 +45,6 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
--   repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
-    hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black]
 -   repo: https://github.com/PyCQA/flake8
     rev: 4.0.1
     hooks:
@@ -86,6 +81,29 @@ repos:
             "{{cookiecutter.project_slug}}"
         ]
         pass_filenames: false
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-gfm,
+            mdformat-black,
+        ]
+        args: [--wrap, "88", --end-of-line, crlf]
+        files: (README\.md)
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-myst,
+            mdformat-black,
+        ]
+        args: [--wrap, "88", --end-of-line, crlf]
+        files: (docs/.)
+        # exclude: |
+        #     (?x)^(
+        #     )$
 -   repo: https://github.com/codespell-project/codespell
     rev: v2.1.0
     hooks:
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37f6ea9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# cookiecutter-pytask-project
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+This repository contains a minimal cookiecutter template for a project with
+[pytask](https://github.com/pytask-dev/pytask).
+
+## Usage
+
+First, install cookiecutter.
+
+```console
+$ pip install cookiecutter
+
+$ conda install -c conda-forge cookiecutter
+```
+
+Then, set up the template with
+
+```console
+$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
+```
+
+## FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
diff --git a/docs/rtd_environment.yml b/docs/rtd_environment.yml
index 25d3cc0..c274c14 100644
--- a/docs/rtd_environment.yml
+++ b/docs/rtd_environment.yml
@@ -12,6 +12,7 @@ dependencies:
   - furo
   - ipython
   - nbsphinx
+  - myst-parser
   - sphinx
   - sphinx-autoapi
   - sphinx-copybutton
diff --git a/docs/source/api.rst b/docs/source/api.md
similarity index 51%
rename from docs/source/api.rst
rename to docs/source/api.md
index d4b8ab8..c63fd9c 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.md
@@ -1,11 +1,12 @@
-API Reference
-=============
+# API Reference
 
 The following documents are auto-generated and not carefully edited. They provide direct
 access to the source code and the docstrings.
 
-.. toctree::
-   :titlesonly:
-
-   /autoapi/pre_gen_project/index
-   /autoapi/post_gen_project/index
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/pre_gen_project/index
+/autoapi/post_gen_project/index
+```
diff --git a/docs/source/changes.md b/docs/source/changes.md
new file mode 100644
index 0000000..7dfd268
--- /dev/null
+++ b/docs/source/changes.md
@@ -0,0 +1,21 @@
+# Changes
+
+This is a record of all past cookiecutter-pytask-project releases and what went into
+them in reverse chronological order.
+
+## 1.2.0 - 2022-xx-xx
+
+- {gh}`7` skips concurrent CI builds.
+- {gh}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
+- {gh}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
+
+## 1.1.0 - 2022-01-16
+
+- {gh}`4` renames the cookiecutter from cookiecutter-pytask to
+  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
+  remove unnecessary packaging stuff.
+
+## 1.0.0 - 2022-01-05
+
+- {gh}`1` creates first release of a minimal cookiecutter template for a pytask project.
+- {gh}`2` adds more tests.
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
deleted file mode 100644
index fb07568..0000000
--- a/docs/source/changes.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-Changes
-=======
-
-This is a record of all past cookiecutter-pytask-project releases and what went into
-them in reverse chronological order.
-
-1.2.0 - 2022-xx-xx
-------------------
-
-- :gh:`7` skips concurrent CI builds.
-- :gh:`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
-- :gh:`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
-
-
-1.1.0 - 2022-01-16
-------------------
-
-- :gh:`4` renames the cookiecutter from cookiecutter-pytask to
-  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
-  remove unnecessary packaging stuff.
-
-
-1.0.0 - 2022-01-05
-------------------
-
-- :gh:`1` creates first release of a minimal cookiecutter template for a pytask project.
-- :gh:`2` adds more tests.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 00ad227..53bf489 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -32,10 +32,12 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinxext.opengraph",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "sphinx_panels",
     "autoapi.extension",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -57,9 +59,12 @@
 copybutton_prompt_is_regexp = True
 
 # Use these roles to create links to github users and pull requests.
+_repo = "https://github.com/pytask-dev/cookiecutter-pytask-project"
 extlinks = {
-    "ghuser": ("https://github.com/%s", "@"),
-    "gh": ("https://github.com/pytask-dev/cookiecutter-pytask-project/pull/%s", "#"),
+    "pypi": ("https://pypi.org/project/%s/", ""),
+    "issue": (f"{_repo}/issues/%s", "issue #"),
+    "pull": (f"{_repo}/pull/%s", "pull request #"),
+    "user": ("https://github.com/%s", "@"),
 }
 
 # Link objects to other documentations.
@@ -68,6 +73,9 @@
     "pytask": ("https://pytask-dev.readthedocs.io/en/stable/", None),
 }
 
+# MyST
+myst_enable_extensions = []
+
 
 # -- Options for HTML output -------------------------------------------------
 
diff --git a/docs/source/index.md b/docs/source/index.md
new file mode 100644
index 0000000..607a167
--- /dev/null
+++ b/docs/source/index.md
@@ -0,0 +1,17 @@
+# Welcome to cookiecutter-pytask-project's documentation!
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+```{toctree}
+---
+caption: 'Contents:'
+maxdepth: 1
+---
+changes
+api
+```
diff --git a/docs/source/index.rst b/docs/source/index.rst
deleted file mode 100644
index 417add8..0000000
--- a/docs/source/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Welcome to cookiecutter-pytask-project's documentation!
-=======================================================
-
-.. include:: ../../README.rst
-
-
-.. toctree::
-    :caption: Contents:
-    :maxdepth: 1
-
-    changes
-    api
diff --git a/environment.yml b/environment.yml
index 34c6388..8ea0ec2 100644
--- a/environment.yml
+++ b/environment.yml
@@ -27,6 +27,7 @@ dependencies:
 
   # Documentation
   - furo
+  - myst-parser
   - nbsphinx
   - sphinx
   - sphinx-autoapi
diff --git a/{{cookiecutter.project_slug}}/docs/rtd_environment.yml b/{{cookiecutter.project_slug}}/docs/rtd_environment.yml
index e08570d..879d111 100644
--- a/{{cookiecutter.project_slug}}/docs/rtd_environment.yml
+++ b/{{cookiecutter.project_slug}}/docs/rtd_environment.yml
@@ -12,6 +12,7 @@ dependencies:
   - furo
   - ipython
   - nbsphinx
+  - myst-parser
   - sphinx
   - sphinx-autoapi
   - sphinx-copybutton
diff --git a/{{cookiecutter.project_slug}}/docs/source/api.rst b/{{cookiecutter.project_slug}}/docs/source/api.md
similarity index 55%
rename from {{cookiecutter.project_slug}}/docs/source/api.rst
rename to {{cookiecutter.project_slug}}/docs/source/api.md
index 536d855..929543a 100644
--- a/{{cookiecutter.project_slug}}/docs/source/api.rst
+++ b/{{cookiecutter.project_slug}}/docs/source/api.md
@@ -1,10 +1,11 @@
-API Reference
-=============
+# API Reference
 
 The following documents are auto-generated and not carefully edited. They provide direct
 access to the source code and the docstrings.
 
-.. toctree::
-   :titlesonly:
-
-   /autoapi/{{ cookiecutter.project_slug }}/index
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/{{ cookiecutter.project_slug }}/index
+```
diff --git a/{{cookiecutter.project_slug}}/docs/source/changes.rst b/{{cookiecutter.project_slug}}/docs/source/changes.md
similarity index 63%
rename from {{cookiecutter.project_slug}}/docs/source/changes.rst
rename to {{cookiecutter.project_slug}}/docs/source/changes.md
index 9defdbd..be87067 100644
--- a/{{cookiecutter.project_slug}}/docs/source/changes.rst
+++ b/{{cookiecutter.project_slug}}/docs/source/changes.md
@@ -1,9 +1,6 @@
-Changes
-=======
+# Changes
 
 This is a record of all past {{ cookiecutter.project_slug }} releases and what went into
 them in reverse chronological order.
 
-
-x.x.x - {% now 'local', '%Y' %}-xx-xx
-------------------
+## x.x.x - {% now 'local', '%Y' %}-xx-xx
diff --git a/{{cookiecutter.project_slug}}/docs/source/conf.py b/{{cookiecutter.project_slug}}/docs/source/conf.py
index dd35d4c..2dddfa3 100644
--- a/{{cookiecutter.project_slug}}/docs/source/conf.py
+++ b/{{cookiecutter.project_slug}}/docs/source/conf.py
@@ -10,11 +10,12 @@
 # -- Project information -----------------------------------------------------
 
 project = "{{ cookiecutter.project_name }}"
+project_slug = "{{ cookiecutter.project_slug }}"
 author = "{{ cookiecutter.author }}"
 copyright = f"2022, {author}"  # noqa: A001
 
 # The version, including alpha/beta/rc tags, but not commit hash and datestamps
-release = version("{{ cookiecutter.project_slug }}")
+release = version(project_slug)
 # The short X.Y version.
 version = ".".join(release.split(".")[:2])
 
@@ -31,10 +32,12 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinxext.opengraph",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "sphinx_panels",
     "autoapi.extension",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -56,13 +59,12 @@
 copybutton_prompt_is_regexp = True
 
 # Use these roles to create links to github users and pull requests.
+_repo = "https://github.com/{{ cookiecutter.github_username }}/" + project_slug
 extlinks = {
-    "ghuser": ("https://github.com/%s", "@"),
-    "gh": (
-        "https://github.com/{{ cookiecutter.github_username }}/"
-        "{{ cookiecutter.project_slug }}/pull/%s",
-        "#",
-    ),
+    "pypi": ("https://pypi.org/project/%s/", ""),
+    "issue": (f"{_repo}/issues/%s", "issue #"),
+    "pull": (f"{_repo}/pull/%s", "pull request #"),
+    "user": ("https://github.com/%s", "@"),
 }
 
 # Link objects to other documentations.
@@ -71,6 +73,9 @@
     "pytask": ("https://pytask-dev.readthedocs.io/en/stable/", None),
 }
 
+# MyST
+myst_enable_extensions = []
+
 
 # -- Options for HTML output -------------------------------------------------
 
diff --git a/{{cookiecutter.project_slug}}/docs/source/index.md b/{{cookiecutter.project_slug}}/docs/source/index.md
new file mode 100644
index 0000000..de2601b
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/docs/source/index.md
@@ -0,0 +1,10 @@
+# Welcome to {{ cookiecutter.project_name }}'s documentation!
+
+```{toctree}
+---
+caption: 'Contents:'
+maxdepth: 1
+---
+changes
+api
+```
diff --git a/{{cookiecutter.project_slug}}/docs/source/index.rst b/{{cookiecutter.project_slug}}/docs/source/index.rst
deleted file mode 100644
index 1317e3c..0000000
--- a/{{cookiecutter.project_slug}}/docs/source/index.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Welcome to {{ cookiecutter.project_name }}'s documentation!
-{% for _ in range(cookiecutter.project_name | length + 28) %}={% endfor %}
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   changes
-   api
diff --git a/{{cookiecutter.project_slug}}/environment.yml b/{{cookiecutter.project_slug}}/environment.yml
index 7320b2e..9169b36 100644
--- a/{{cookiecutter.project_slug}}/environment.yml
+++ b/{{cookiecutter.project_slug}}/environment.yml
@@ -27,6 +27,7 @@ dependencies:
 
   # Documentation
   - furo
+  - myst-parser
   - nbsphinx
   - sphinx
   - sphinx-autoapi

From 15fe4ee7fab159e3676738d5db033a08f295c581 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 00:39:58 +0200
Subject: [PATCH 02/12] Move to markdown.

---
 README.rst                               | 59 ------------------------
 {{cookiecutter.project_slug}}/README.rst | 43 -----------------
 2 files changed, 102 deletions(-)
 delete mode 100644 README.rst
 delete mode 100644 {{cookiecutter.project_slug}}/README.rst

diff --git a/README.rst b/README.rst
deleted file mode 100644
index 9ea89a9..0000000
--- a/README.rst
+++ /dev/null
@@ -1,59 +0,0 @@
-cookiecutter-pytask-project
-===========================
-
-.. image:: https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project
-    :alt: MIT license
-    :target: https://github.com/pytask-dev/cookiecutter-pytask-project
-
-.. image:: https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest
-    :target: https://cookiecutter-pytask-project.readthedocs.io/en/latest
-
-.. image:: https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main
-   :target: https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain
-
-.. image:: https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg
-    :target: https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project
-
-.. image:: https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg
-    :target: https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main
-    :alt: pre-commit.ci status
-
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/psf/black
-
-
-This repository contains a minimal cookiecutter template for a project with `pytask
-<https://github.com/pytask-dev/pytask>`_ .
-
-
-Usage
------
-
-First, install cookiecutter.
-
-.. code-block:: console
-
-    $ pip install cookiecutter
-
-    $ conda install -c conda-forge cookiecutter
-
-Then, set up the template with
-
-.. code-block:: console
-
-    $ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
-
-
-FAQ
----
-
-Q: Why are the source files nested in ``src/<project_slug>``?
-
-A: This is called the src layout and the advantages are discussed in this `article by
-Hynek Schlawack <https://hynek.me/articles/testing-packaging/>`_.
-
-Although the article discusses the src layout in terms of Python packages, it is also
-beneficial to structure a project the same way. Next to the reasons discussed there, it
-is possible to use a single Python environment for multiple projects without messing
-with your PYTHONPATH (via ``pip install -e .`` or ``conda develop .``) each time and
-still import modules.
diff --git a/{{cookiecutter.project_slug}}/README.rst b/{{cookiecutter.project_slug}}/README.rst
deleted file mode 100644
index 1a6c493..0000000
--- a/{{cookiecutter.project_slug}}/README.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-{{ cookiecutter.project_name }}
-{% for _ in cookiecutter.project_name %}={% endfor %}
-
-{% if cookiecutter.add_github_actions == "yes" %}.. image:: https://img.shields.io/github/workflow/status/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main/main
-    :target: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/actions?query=branch%3Amain
-{% endif %}
-{% if cookiecutter.add_readthedocs == "yes" %}.. image:: https://readthedocs.org/projects/{{ cookiecutter.project_slug | replace("_", "-") }}/badge/?version=latest
-    :target: https://{{ cookiecutter.project_slug | replace("_", "-") }}.readthedocs.io/en/latest/?badge=latest
-    :alt: Documentation Status
-{% endif %}
-{% if cookiecutter.add_codecov == "yes" %}.. image:: https://codecov.io/gh/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/branch/main/graph/badge.svg
-    :target: https://codecov.io/gh/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}
-{% endif %}
-.. image:: https://results.pre-commit.ci/badge/github/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main.svg
-    :target: https://results.pre-commit.ci/latest/github/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main
-    :alt: pre-commit.ci status
-
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/ambv/black
-
-
-Usage
------
-
-To get started, create the environment with
-
-.. code-block:: console
-
-    $ conda/mamba env create
-
-To build the project, type
-
-.. code-block:: console
-
-    $ pytask
-
-
-Credits
--------
-
-This project was created with `cookiecutter <https://github.com/audreyr/cookiecutter>`_
-and the `cookiecutter-pytask-project
-<https://github.com/pytask-dev/cookiecutter-pytask-project>`_ template.

From db9fec66efd55463b8b40a11af0922b2f07f5e23 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 00:43:06 +0200
Subject: [PATCH 03/12] fix.

---
 .pre-commit-config.yaml                       |  7 ----
 .../.pre-commit-config.yaml                   | 12 -------
 {{cookiecutter.project_slug}}/README.md       | 33 +++++++++++++++++++
 3 files changed, 33 insertions(+), 19 deletions(-)
 create mode 100644 {{cookiecutter.project_slug}}/README.md

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f1aba5e..5b7518f 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -28,9 +28,6 @@ repos:
     -   id: python-no-eval
     -   id: python-no-log-warn
     -   id: python-use-type-annotations
-    -   id: rst-backticks
-    -   id: rst-directive-colons
-    -   id: rst-inline-touching-normal
     -   id: text-unicode-replacement-char
 -   repo: https://github.com/asottile/pyupgrade
     rev: v2.32.0
@@ -65,10 +62,6 @@ repos:
             pydocstyle,
             Pygments,
         ]
--   repo: https://github.com/PyCQA/doc8
-    rev: 0.11.1
-    hooks:
-    -   id: doc8
 -   repo: https://github.com/econchick/interrogate
     rev: 1.5.0
     hooks:
diff --git a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
index 68a1d34..82722c0 100644
--- a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
+++ b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
@@ -23,9 +23,6 @@ repos:
     -   id: python-no-eval
     -   id: python-no-log-warn
     -   id: python-use-type-annotations
-    -   id: rst-backticks
-    -   id: rst-directive-colons
-    -   id: rst-inline-touching-normal
     -   id: text-unicode-replacement-char
 -   repo: https://github.com/asottile/pyupgrade
     rev: v2.32.0
@@ -45,11 +42,6 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
--   repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
-    hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black]
 -   repo: https://github.com/PyCQA/flake8
     rev: 4.0.1
     hooks:
@@ -70,10 +62,6 @@ repos:
             pydocstyle,
             Pygments,
         ]
--   repo: https://github.com/PyCQA/doc8
-    rev: 0.11.1
-    hooks:
-    -   id: doc8
 -   repo: https://github.com/econchick/interrogate
     rev: 1.5.0
     hooks:
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
new file mode 100644
index 0000000..8dbd2a1
--- /dev/null
+++ b/{{cookiecutter.project_slug}}/README.md
@@ -0,0 +1,33 @@
+# {{ cookiecutter.project_name }}
+
+{% if cookiecutter.add_github_actions == "yes" %}[![image](https://img.shields.io/github/workflow/status/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main/main)](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/actions?query=branch%3Amain)
+{% endif %}
+{% if cookiecutter.add_readthedocs == "yes" %}[![image](https://readthedocs.org/projects/{{ cookiecutter.project_slug | replace("_", "-") }}/badge/?version=stable)](https://{{ cookiecutter.project_slug | replace("_", "-") }}.readthedocs.io/en/stable/?badge=stable)
+{% endif %}
+{% if cookiecutter.add_codecov == "yes" %}[![image](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/branch/main/graph/badge.svg)](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }})
+{% endif %}
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main.svg)](https://results.pre-commit.ci/latest/github/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+Usage
+-----
+
+To get started, create the environment with
+
+.. code-block:: console
+
+    $ conda/mamba env create
+
+To build the project, type
+
+.. code-block:: console
+
+    $ pytask
+
+
+Credits
+-------
+
+This project was created with `cookiecutter <https://github.com/audreyr/cookiecutter>`_
+and the `cookiecutter-pytask-project
+<https://github.com/pytask-dev/cookiecutter-pytask-project>`_ template.

From d435ba52a7385796ea6fa27eb24ccf688cd316db Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 00:46:52 +0200
Subject: [PATCH 04/12] to changes.

---
 docs/source/changes.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/source/changes.md b/docs/source/changes.md
index 7dfd268..9768812 100644
--- a/docs/source/changes.md
+++ b/docs/source/changes.md
@@ -5,17 +5,23 @@ them in reverse chronological order.
 
 ## 1.2.0 - 2022-xx-xx
 
-- {gh}`7` skips concurrent CI builds.
-- {gh}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
-- {gh}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
+- {pull}`7` skips concurrent CI builds.
+- {pull}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
+- {pull}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
+- {pull}`12` removes `LICENSE` from `MANIFEST.in` if no license is selected.
+- {pull}`13` adds a `.gitignore`.
+- {pull}`14` adds a `CITATION`.
+- {pull}`15` cancels concurrent CI jobs.
+- {pull}`18` fixes {issue}`17` and moves rst to markdown.
 
 ## 1.1.0 - 2022-01-16
 
-- {gh}`4` renames the cookiecutter from cookiecutter-pytask to
+- {pull}`4` renames the cookiecutter from cookiecutter-pytask to
   cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
   remove unnecessary packaging stuff.
 
 ## 1.0.0 - 2022-01-05
 
-- {gh}`1` creates first release of a minimal cookiecutter template for a pytask project.
-- {gh}`2` adds more tests.
+- {pull}`1` creates first release of a minimal cookiecutter template for a pytask
+  project.
+- {pull}`2` adds more tests.

From 762d3198dfd068dd2e7ae000771cdcb44f3e5d04 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 13 Apr 2022 22:48:48 +0000
Subject: [PATCH 05/12] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 README.md                                     | 80 +++++++++----------
 docs/source/api.md                            | 24 +++---
 docs/source/changes.md                        | 54 ++++++-------
 docs/source/index.md                          | 34 ++++----
 {{cookiecutter.project_slug}}/README.md       | 77 ++++++++++--------
 .../docs/source/api.md                        | 22 ++---
 .../docs/source/changes.md                    | 12 +--
 .../docs/source/index.md                      | 20 ++---
 8 files changed, 167 insertions(+), 156 deletions(-)

diff --git a/README.md b/README.md
index 37f6ea9..be90cd3 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,40 @@
-# cookiecutter-pytask-project
-
-[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
-[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
-[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
-[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-This repository contains a minimal cookiecutter template for a project with
-[pytask](https://github.com/pytask-dev/pytask).
-
-## Usage
-
-First, install cookiecutter.
-
-```console
-$ pip install cookiecutter
-
-$ conda install -c conda-forge cookiecutter
-```
-
-Then, set up the template with
-
-```console
-$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
-```
-
-## FAQ
-
-Q: Why are the source files nested in `src/<project_slug>`?
-
-A: This is called the src layout and the advantages are discussed in this
-[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
-
-Although the article discusses the src layout in terms of Python packages, it is also
-beneficial to structure a project the same way. Next to the reasons discussed there, it
-is possible to use a single Python environment for multiple projects without messing
-with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
-import modules.
+# cookiecutter-pytask-project
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+This repository contains a minimal cookiecutter template for a project with
+[pytask](https://github.com/pytask-dev/pytask).
+
+## Usage
+
+First, install cookiecutter.
+
+```console
+$ pip install cookiecutter
+
+$ conda install -c conda-forge cookiecutter
+```
+
+Then, set up the template with
+
+```console
+$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
+```
+
+## FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
diff --git a/docs/source/api.md b/docs/source/api.md
index c63fd9c..e64085c 100644
--- a/docs/source/api.md
+++ b/docs/source/api.md
@@ -1,12 +1,12 @@
-# API Reference
-
-The following documents are auto-generated and not carefully edited. They provide direct
-access to the source code and the docstrings.
-
-```{toctree}
----
-titlesonly: true
----
-/autoapi/pre_gen_project/index
-/autoapi/post_gen_project/index
-```
+# API Reference
+
+The following documents are auto-generated and not carefully edited. They provide direct
+access to the source code and the docstrings.
+
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/pre_gen_project/index
+/autoapi/post_gen_project/index
+```
diff --git a/docs/source/changes.md b/docs/source/changes.md
index 9768812..43bf838 100644
--- a/docs/source/changes.md
+++ b/docs/source/changes.md
@@ -1,27 +1,27 @@
-# Changes
-
-This is a record of all past cookiecutter-pytask-project releases and what went into
-them in reverse chronological order.
-
-## 1.2.0 - 2022-xx-xx
-
-- {pull}`7` skips concurrent CI builds.
-- {pull}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
-- {pull}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
-- {pull}`12` removes `LICENSE` from `MANIFEST.in` if no license is selected.
-- {pull}`13` adds a `.gitignore`.
-- {pull}`14` adds a `CITATION`.
-- {pull}`15` cancels concurrent CI jobs.
-- {pull}`18` fixes {issue}`17` and moves rst to markdown.
-
-## 1.1.0 - 2022-01-16
-
-- {pull}`4` renames the cookiecutter from cookiecutter-pytask to
-  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
-  remove unnecessary packaging stuff.
-
-## 1.0.0 - 2022-01-05
-
-- {pull}`1` creates first release of a minimal cookiecutter template for a pytask
-  project.
-- {pull}`2` adds more tests.
+# Changes
+
+This is a record of all past cookiecutter-pytask-project releases and what went into
+them in reverse chronological order.
+
+## 1.2.0 - 2022-xx-xx
+
+- {pull}`7` skips concurrent CI builds.
+- {pull}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
+- {pull}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
+- {pull}`12` removes `LICENSE` from `MANIFEST.in` if no license is selected.
+- {pull}`13` adds a `.gitignore`.
+- {pull}`14` adds a `CITATION`.
+- {pull}`15` cancels concurrent CI jobs.
+- {pull}`18` fixes {issue}`17` and moves rst to markdown.
+
+## 1.1.0 - 2022-01-16
+
+- {pull}`4` renames the cookiecutter from cookiecutter-pytask to
+  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
+  remove unnecessary packaging stuff.
+
+## 1.0.0 - 2022-01-05
+
+- {pull}`1` creates first release of a minimal cookiecutter template for a pytask
+  project.
+- {pull}`2` adds more tests.
diff --git a/docs/source/index.md b/docs/source/index.md
index 607a167..cd73e8b 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -1,17 +1,17 @@
-# Welcome to cookiecutter-pytask-project's documentation!
-
-[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
-[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
-[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
-[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-```{toctree}
----
-caption: 'Contents:'
-maxdepth: 1
----
-changes
-api
-```
+# Welcome to cookiecutter-pytask-project's documentation!
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+```{toctree}
+---
+caption: 'Contents:'
+maxdepth: 1
+---
+changes
+api
+```
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
index 8dbd2a1..3667e02 100644
--- a/{{cookiecutter.project_slug}}/README.md
+++ b/{{cookiecutter.project_slug}}/README.md
@@ -1,33 +1,44 @@
-# {{ cookiecutter.project_name }}
-
-{% if cookiecutter.add_github_actions == "yes" %}[![image](https://img.shields.io/github/workflow/status/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main/main)](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/actions?query=branch%3Amain)
-{% endif %}
-{% if cookiecutter.add_readthedocs == "yes" %}[![image](https://readthedocs.org/projects/{{ cookiecutter.project_slug | replace("_", "-") }}/badge/?version=stable)](https://{{ cookiecutter.project_slug | replace("_", "-") }}.readthedocs.io/en/stable/?badge=stable)
-{% endif %}
-{% if cookiecutter.add_codecov == "yes" %}[![image](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/branch/main/graph/badge.svg)](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }})
-{% endif %}
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main.svg)](https://results.pre-commit.ci/latest/github/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-Usage
------
-
-To get started, create the environment with
-
-.. code-block:: console
-
-    $ conda/mamba env create
-
-To build the project, type
-
-.. code-block:: console
-
-    $ pytask
-
-
-Credits
--------
-
-This project was created with `cookiecutter <https://github.com/audreyr/cookiecutter>`_
-and the `cookiecutter-pytask-project
-<https://github.com/pytask-dev/cookiecutter-pytask-project>`_ template.
+# {{ cookiecutter.project_name }}
+
+{% if cookiecutter.add_github_actions == "yes"
+%}\[!\[image\](https://img.shields.io/github/workflow/status/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug
+}}/main/main)\](https://github.com/{{ cookiecutter.github_username }}/{{
+cookiecutter.project_slug }}/actions?query=branch%3Amain) {% endif %} {% if
+cookiecutter.add_readthedocs == "yes" %}\[!\[image\](https://readthedocs.org/projects/{{
+cookiecutter.project_slug | replace("_", "-") }}/badge/?version=stable)\](https://{{
+cookiecutter.project_slug | replace("_", "-") }}.readthedocs.io/en/stable/?badge=stable)
+{% endif %} {% if cookiecutter.add_codecov == "yes"
+%}\[!\[image\](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{
+cookiecutter.project_slug }}/branch/main/graph/badge.svg)\](https://codecov.io/gh/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug }}) {% endif %}
+\[!\[pre-commit.ci status\](https://results.pre-commit.ci/badge/github/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug
+}}/main.svg)\](https://results.pre-commit.ci/latest/github/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+## Usage
+
+To get started, create the environment with
+
+.. code-block:: console
+
+```
+$ conda/mamba env create
+```
+
+To build the project, type
+
+.. code-block:: console
+
+```
+$ pytask
+```
+
+## Credits
+
+This project was created with `cookiecutter <https://github.com/audreyr/cookiecutter>`\_
+and the
+`cookiecutter-pytask-project <https://github.com/pytask-dev/cookiecutter-pytask-project>`\_
+template.
diff --git a/{{cookiecutter.project_slug}}/docs/source/api.md b/{{cookiecutter.project_slug}}/docs/source/api.md
index 929543a..516a46e 100644
--- a/{{cookiecutter.project_slug}}/docs/source/api.md
+++ b/{{cookiecutter.project_slug}}/docs/source/api.md
@@ -1,11 +1,11 @@
-# API Reference
-
-The following documents are auto-generated and not carefully edited. They provide direct
-access to the source code and the docstrings.
-
-```{toctree}
----
-titlesonly: true
----
-/autoapi/{{ cookiecutter.project_slug }}/index
-```
+# API Reference
+
+The following documents are auto-generated and not carefully edited. They provide direct
+access to the source code and the docstrings.
+
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/{{ cookiecutter.project_slug }}/index
+```
diff --git a/{{cookiecutter.project_slug}}/docs/source/changes.md b/{{cookiecutter.project_slug}}/docs/source/changes.md
index be87067..4680c7c 100644
--- a/{{cookiecutter.project_slug}}/docs/source/changes.md
+++ b/{{cookiecutter.project_slug}}/docs/source/changes.md
@@ -1,6 +1,6 @@
-# Changes
-
-This is a record of all past {{ cookiecutter.project_slug }} releases and what went into
-them in reverse chronological order.
-
-## x.x.x - {% now 'local', '%Y' %}-xx-xx
+# Changes
+
+This is a record of all past {{ cookiecutter.project_slug }} releases and what went into
+them in reverse chronological order.
+
+## x.x.x - {% now 'local', '%Y' %}-xx-xx
diff --git a/{{cookiecutter.project_slug}}/docs/source/index.md b/{{cookiecutter.project_slug}}/docs/source/index.md
index de2601b..9a76d5e 100644
--- a/{{cookiecutter.project_slug}}/docs/source/index.md
+++ b/{{cookiecutter.project_slug}}/docs/source/index.md
@@ -1,10 +1,10 @@
-# Welcome to {{ cookiecutter.project_name }}'s documentation!
-
-```{toctree}
----
-caption: 'Contents:'
-maxdepth: 1
----
-changes
-api
-```
+# Welcome to {{ cookiecutter.project_name }}'s documentation!
+
+```{toctree}
+---
+caption: 'Contents:'
+maxdepth: 1
+---
+changes
+api
+```

From 62483640307c518f156e743b683ba21893cde990 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 00:56:08 +0200
Subject: [PATCH 06/12] add missing opengraph.

---
 docs/rtd_environment.yml                               | 3 ++-
 {{cookiecutter.project_slug}}/docs/rtd_environment.yml | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/rtd_environment.yml b/docs/rtd_environment.yml
index c274c14..2263961 100644
--- a/docs/rtd_environment.yml
+++ b/docs/rtd_environment.yml
@@ -19,4 +19,5 @@ dependencies:
   - sphinx-panels
 
   - pip:
-    - -e ../
+    - ../
+    - sphinxext-opengraph
diff --git a/{{cookiecutter.project_slug}}/docs/rtd_environment.yml b/{{cookiecutter.project_slug}}/docs/rtd_environment.yml
index 879d111..beea111 100644
--- a/{{cookiecutter.project_slug}}/docs/rtd_environment.yml
+++ b/{{cookiecutter.project_slug}}/docs/rtd_environment.yml
@@ -17,3 +17,7 @@ dependencies:
   - sphinx-autoapi
   - sphinx-copybutton
   - sphinx-panels
+
+  - pip:
+    - ../
+    - sphinxext-opengraph

From 1a678f797fd8a0bbc4516ee77d2d90fc21789569 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 01:18:27 +0200
Subject: [PATCH 07/12] fix readem.

---
 tests/test_cookie.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_cookie.py b/tests/test_cookie.py
index 93ba4f5..8844dd5 100644
--- a/tests/test_cookie.py
+++ b/tests/test_cookie.py
@@ -25,7 +25,7 @@ def test_remove_readthedocs(cookies):
     result = cookies.bake(extra_context={"add_readthedocs": "no"})
 
     rtd_config = result.project_path.joinpath(".readthedocs.yaml")
-    readme = result.project_path.joinpath("README.rst").read_text()
+    readme = result.project_path.joinpath("README.md").read_text()
 
     assert result.exit_code == 0
     assert result.exception is None
@@ -39,7 +39,7 @@ def test_remove_github_actions(cookies):
     result = cookies.bake(extra_context={"add_github_actions": "no"})
 
     ga_config = result.project_path.joinpath(".github", "workflows", "main.yml")
-    readme = result.project_path.joinpath("README.rst").read_text()
+    readme = result.project_path.joinpath("README.md").read_text()
 
     assert result.exit_code == 0
     assert result.exception is None

From d0ee7c93f23467e204b92a9170542c0f7a7d1011 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 09:54:33 +0200
Subject: [PATCH 08/12] fix readem.

---
 environment.yml                               | 4 ++++
 {{cookiecutter.project_slug}}/environment.yml | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/environment.yml b/environment.yml
index 8ea0ec2..97a4c5b 100644
--- a/environment.yml
+++ b/environment.yml
@@ -34,3 +34,7 @@ dependencies:
   - sphinx-click
   - sphinx-copybutton
   - sphinx-panels
+
+  - pip:
+    - ../
+    - sphinxext-opengraph
diff --git a/{{cookiecutter.project_slug}}/environment.yml b/{{cookiecutter.project_slug}}/environment.yml
index 9169b36..643daf3 100644
--- a/{{cookiecutter.project_slug}}/environment.yml
+++ b/{{cookiecutter.project_slug}}/environment.yml
@@ -34,3 +34,7 @@ dependencies:
   - sphinx-click
   - sphinx-copybutton
   - sphinx-panels
+
+  - pip:
+    - ../
+    - sphinxext-opengraph

From 90574f761ac8ce8d4e4b74476bf32bbd6de2b66b Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 10:01:25 +0200
Subject: [PATCH 09/12] remove editable install from root.

---
 environment.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/environment.yml b/environment.yml
index 97a4c5b..096144d 100644
--- a/environment.yml
+++ b/environment.yml
@@ -36,5 +36,4 @@ dependencies:
   - sphinx-panels
 
   - pip:
-    - ../
     - sphinxext-opengraph

From b0e56df3999aa0d0ffaa7e8d4e574749b361c8c6 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 10:10:26 +0200
Subject: [PATCH 10/12] fix.

---
 {{cookiecutter.project_slug}}/environment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/{{cookiecutter.project_slug}}/environment.yml b/{{cookiecutter.project_slug}}/environment.yml
index 643daf3..6b0a124 100644
--- a/{{cookiecutter.project_slug}}/environment.yml
+++ b/{{cookiecutter.project_slug}}/environment.yml
@@ -36,5 +36,5 @@ dependencies:
   - sphinx-panels
 
   - pip:
-    - ../
+    - -e .
     - sphinxext-opengraph

From 3d8c6d36a372758ce6aa1b513e96964265287e69 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 11:02:42 +0200
Subject: [PATCH 11/12] to lf line endings.

---
 .pre-commit-config.yaml                       |   6 +-
 README.md                                     | 123 ++++++++++++------
 docs/source/api.md                            |  24 ++--
 docs/source/changes.md                        |  54 ++++----
 docs/source/index.md                          |  66 +++++++---
 .../.pre-commit-config.yaml                   |  31 ++++-
 {{cookiecutter.project_slug}}/README.md       |  88 ++++++-------
 .../docs/source/api.md                        |  22 ++--
 .../docs/source/changes.md                    |  12 +-
 .../docs/source/index.md                      |  20 +--
 10 files changed, 274 insertions(+), 172 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5b7518f..f5bd7a0 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -82,7 +82,7 @@ repos:
             mdformat-gfm,
             mdformat-black,
         ]
-        args: [--wrap, "88", --end-of-line, crlf]
+        args: [--wrap, "88"]
         files: (README\.md)
 -   repo: https://github.com/executablebooks/mdformat
     rev: 0.7.14
@@ -92,10 +92,12 @@ repos:
             mdformat-myst,
             mdformat-black,
         ]
-        args: [--wrap, "88", --end-of-line, crlf]
+        args: [--wrap, "88"]
         files: (docs/.)
+        # Exclude files with admonitions.
         # exclude: |
         #     (?x)^(
+        #         path/to/file.py
         #     )$
 -   repo: https://github.com/codespell-project/codespell
     rev: v2.1.0
diff --git a/README.md b/README.md
index be90cd3..fe92c2e 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,83 @@
-# cookiecutter-pytask-project
-
-[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
-[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
-[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
-[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-This repository contains a minimal cookiecutter template for a project with
-[pytask](https://github.com/pytask-dev/pytask).
-
-## Usage
-
-First, install cookiecutter.
-
-```console
-$ pip install cookiecutter
-
-$ conda install -c conda-forge cookiecutter
-```
-
-Then, set up the template with
-
-```console
-$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
-```
-
-## FAQ
-
-Q: Why are the source files nested in `src/<project_slug>`?
-
-A: This is called the src layout and the advantages are discussed in this
-[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
-
-Although the article discusses the src layout in terms of Python packages, it is also
-beneficial to structure a project the same way. Next to the reasons discussed there, it
-is possible to use a single Python environment for multiple projects without messing
-with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
-import modules.
+# cookiecutter-pytask-project
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+This repository contains a minimal cookiecutter template for a project with
+[pytask](https://github.com/pytask-dev/pytask).
+
+## Usage
+
+First, install cookiecutter.
+
+```console
+$ pip install cookiecutter
+
+$ conda install -c conda-forge cookiecutter
+```
+
+Then, set up the template with
+
+```console
+$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
+```
+
+## Documentation
+
+If you are new to pytask, just follow the
+[tutorials](https://pytask-dev.readthedocs.io/en/stable/tutorials/index.html) which will
+help you with your first steps like how to write the first task.
+
+If you are already familiar with pytask, the
+[how-to guides](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/index.html)
+offer more in-depth guidance on complex projects.
+
+In general, you will find most guidance in the
+[documentation](https://pytask-dev.readthedocs.io/en/stable/index.html) and some advice
+in the FAQ below.
+
+## FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
+
+Q: My project is a Python package, but it does not seem to have a version. Where is it?
+
+A: The cookiecutter uses [setuptools_scm](https://github.com/pypa/setuptools_scm/) to
+manage the version number. When you install your created project as a Python package
+with `pip install -e .`, setuptools_scm tries to infer the version number from the tags
+created on the repo.
+
+For example, if you have switched to a commit associated with the tag `v0.2.0`,
+setuptools_scm will create a `src/<package_slug>/_version.py` with a variable containing
+`version = '0.2.0'` which you can use in your `src/<package_slug>/__init__.py`. If you
+are one commit ahead of the tag, you version will be something like `0.2.0.dev1+...`
+indicating you are one commit ahead of the tag `v0.2.0`.
+
+If you want to switch to the tradition setup, replace the following code in your
+`pyproject.toml`
+
+```toml
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]
+```
+
+with
+
+```toml
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+```
diff --git a/docs/source/api.md b/docs/source/api.md
index e64085c..c63fd9c 100644
--- a/docs/source/api.md
+++ b/docs/source/api.md
@@ -1,12 +1,12 @@
-# API Reference
-
-The following documents are auto-generated and not carefully edited. They provide direct
-access to the source code and the docstrings.
-
-```{toctree}
----
-titlesonly: true
----
-/autoapi/pre_gen_project/index
-/autoapi/post_gen_project/index
-```
+# API Reference
+
+The following documents are auto-generated and not carefully edited. They provide direct
+access to the source code and the docstrings.
+
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/pre_gen_project/index
+/autoapi/post_gen_project/index
+```
diff --git a/docs/source/changes.md b/docs/source/changes.md
index 43bf838..9768812 100644
--- a/docs/source/changes.md
+++ b/docs/source/changes.md
@@ -1,27 +1,27 @@
-# Changes
-
-This is a record of all past cookiecutter-pytask-project releases and what went into
-them in reverse chronological order.
-
-## 1.2.0 - 2022-xx-xx
-
-- {pull}`7` skips concurrent CI builds.
-- {pull}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
-- {pull}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
-- {pull}`12` removes `LICENSE` from `MANIFEST.in` if no license is selected.
-- {pull}`13` adds a `.gitignore`.
-- {pull}`14` adds a `CITATION`.
-- {pull}`15` cancels concurrent CI jobs.
-- {pull}`18` fixes {issue}`17` and moves rst to markdown.
-
-## 1.1.0 - 2022-01-16
-
-- {pull}`4` renames the cookiecutter from cookiecutter-pytask to
-  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
-  remove unnecessary packaging stuff.
-
-## 1.0.0 - 2022-01-05
-
-- {pull}`1` creates first release of a minimal cookiecutter template for a pytask
-  project.
-- {pull}`2` adds more tests.
+# Changes
+
+This is a record of all past cookiecutter-pytask-project releases and what went into
+them in reverse chronological order.
+
+## 1.2.0 - 2022-xx-xx
+
+- {pull}`7` skips concurrent CI builds.
+- {pull}`8` harmonizes cookiecutter-pytask-project with econ-project-templates.
+- {pull}`9` deprecates Python 3.6, add support for Python 3.10 and add mypy optionally.
+- {pull}`12` removes `LICENSE` from `MANIFEST.in` if no license is selected.
+- {pull}`13` adds a `.gitignore`.
+- {pull}`14` adds a `CITATION`.
+- {pull}`15` cancels concurrent CI jobs.
+- {pull}`18` fixes {issue}`17` and moves rst to markdown.
+
+## 1.1.0 - 2022-01-16
+
+- {pull}`4` renames the cookiecutter from cookiecutter-pytask to
+  cookiecutter-pytask-project to avoid confusion with the cookiecutter for plugins. And
+  remove unnecessary packaging stuff.
+
+## 1.0.0 - 2022-01-05
+
+- {pull}`1` creates first release of a minimal cookiecutter template for a pytask
+  project.
+- {pull}`2` adds more tests.
diff --git a/docs/source/index.md b/docs/source/index.md
index cd73e8b..4e50a38 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -1,17 +1,49 @@
-# Welcome to cookiecutter-pytask-project's documentation!
-
-[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
-[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
-[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
-[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-```{toctree}
----
-caption: 'Contents:'
-maxdepth: 1
----
-changes
-api
-```
+# Welcome to cookiecutter-pytask-project's documentation!
+
+[![MIT license](https://img.shields.io/github/license/pytask-dev/cookiecutter-pytask-project)](https://github.com/pytask-dev/cookiecutter-pytask-project)
+[![image](https://readthedocs.org/projects/cookiecutter-pytask-project/badge/?version=latest)](https://cookiecutter-pytask-project.readthedocs.io/en/latest)
+[![image](https://img.shields.io/github/workflow/status/pytask-dev/cookiecutter-pytask-project/main/main)](https://github.com/pytask-dev/cookiecutter-pytask-project/actions?query=branch%3Amain)
+[![image](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/cookiecutter-pytask-project)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/cookiecutter-pytask-project/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/cookiecutter-pytask-project/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+This repository contains a minimal cookiecutter template for a project with
+[pytask](https://github.com/pytask-dev/pytask).
+
+## Usage
+
+First, install cookiecutter.
+
+```console
+$ pip install cookiecutter
+
+$ conda install -c conda-forge cookiecutter
+```
+
+Then, set up the template with
+
+```console
+$ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
+```
+
+## FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
+
+```{toctree}
+---
+caption: 'Contents:'
+maxdepth: 1
+---
+changes
+api
+```
diff --git a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
index 82722c0..f1acd85 100644
--- a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
+++ b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
@@ -62,6 +62,10 @@ repos:
             pydocstyle,
             Pygments,
         ]
+-   repo: https://github.com/guilatrova/tryceratops
+    rev: v1.0.1
+    hooks:
+    -   id: tryceratops
 -   repo: https://github.com/econchick/interrogate
     rev: 1.5.0
     hooks:
@@ -71,10 +75,31 @@ repos:
     rev: v2.1.0
     hooks:
     -   id: codespell
--   repo: https://github.com/guilatrova/tryceratops
-    rev: v1.0.1
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
     hooks:
-    -   id: tryceratops
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-gfm,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (README\.md)
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-myst,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (docs/.)
+        # Exclude files with admonitions.
+        # exclude: |
+        #     (?x)^(
+        #         path/to/file.py
+        #     )$
 {% if cookiecutter.add_mypy == "yes" %}-   repo: https://github.com/pre-commit/mirrors-mypy
     rev: 'v0.942'
     hooks:
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
index 3667e02..635c2ab 100644
--- a/{{cookiecutter.project_slug}}/README.md
+++ b/{{cookiecutter.project_slug}}/README.md
@@ -1,44 +1,44 @@
-# {{ cookiecutter.project_name }}
-
-{% if cookiecutter.add_github_actions == "yes"
-%}\[!\[image\](https://img.shields.io/github/workflow/status/{{
-cookiecutter.github_username }}/{{ cookiecutter.project_slug
-}}/main/main)\](https://github.com/{{ cookiecutter.github_username }}/{{
-cookiecutter.project_slug }}/actions?query=branch%3Amain) {% endif %} {% if
-cookiecutter.add_readthedocs == "yes" %}\[!\[image\](https://readthedocs.org/projects/{{
-cookiecutter.project_slug | replace("_", "-") }}/badge/?version=stable)\](https://{{
-cookiecutter.project_slug | replace("_", "-") }}.readthedocs.io/en/stable/?badge=stable)
-{% endif %} {% if cookiecutter.add_codecov == "yes"
-%}\[!\[image\](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{
-cookiecutter.project_slug }}/branch/main/graph/badge.svg)\](https://codecov.io/gh/{{
-cookiecutter.github_username }}/{{ cookiecutter.project_slug }}) {% endif %}
-\[!\[pre-commit.ci status\](https://results.pre-commit.ci/badge/github/{{
-cookiecutter.github_username }}/{{ cookiecutter.project_slug
-}}/main.svg)\](https://results.pre-commit.ci/latest/github/{{
-cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main)
-[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-## Usage
-
-To get started, create the environment with
-
-.. code-block:: console
-
-```
-$ conda/mamba env create
-```
-
-To build the project, type
-
-.. code-block:: console
-
-```
-$ pytask
-```
-
-## Credits
-
-This project was created with `cookiecutter <https://github.com/audreyr/cookiecutter>`\_
-and the
-`cookiecutter-pytask-project <https://github.com/pytask-dev/cookiecutter-pytask-project>`\_
-template.
+# {{ cookiecutter.project_name }}
+
+{% if cookiecutter.add_github_actions == "yes"
+%}\[!\[image\](https://img.shields.io/github/workflow/status/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug
+}}/main/main)\](https://github.com/{{ cookiecutter.github_username }}/{{
+cookiecutter.project_slug }}/actions?query=branch%3Amain) {% endif %} {% if
+cookiecutter.add_readthedocs == "yes" %}\[!\[image\](https://readthedocs.org/projects/{{
+cookiecutter.project_slug | replace("_", "-") }}/badge/?version=stable)\](https://{{
+cookiecutter.project_slug | replace("_", "-") }}.readthedocs.io/en/stable/?badge=stable)
+{% endif %} {% if cookiecutter.add_codecov == "yes"
+%}\[!\[image\](https://codecov.io/gh/{{ cookiecutter.github_username }}/{{
+cookiecutter.project_slug }}/branch/main/graph/badge.svg)\](https://codecov.io/gh/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug }}) {% endif %}
+\[!\[pre-commit.ci status\](https://results.pre-commit.ci/badge/github/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug
+}}/main.svg)\](https://results.pre-commit.ci/latest/github/{{
+cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/main)
+[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+## Usage
+
+To get started, create the environment with
+
+.. code-block:: console
+
+```
+$ conda/mamba env create
+```
+
+To build the project, type
+
+.. code-block:: console
+
+```
+$ pytask
+```
+
+## Credits
+
+This project was created with `cookiecutter <https://github.com/audreyr/cookiecutter>`\_
+and the
+`cookiecutter-pytask-project <https://github.com/pytask-dev/cookiecutter-pytask-project>`\_
+template.
diff --git a/{{cookiecutter.project_slug}}/docs/source/api.md b/{{cookiecutter.project_slug}}/docs/source/api.md
index 516a46e..929543a 100644
--- a/{{cookiecutter.project_slug}}/docs/source/api.md
+++ b/{{cookiecutter.project_slug}}/docs/source/api.md
@@ -1,11 +1,11 @@
-# API Reference
-
-The following documents are auto-generated and not carefully edited. They provide direct
-access to the source code and the docstrings.
-
-```{toctree}
----
-titlesonly: true
----
-/autoapi/{{ cookiecutter.project_slug }}/index
-```
+# API Reference
+
+The following documents are auto-generated and not carefully edited. They provide direct
+access to the source code and the docstrings.
+
+```{toctree}
+---
+titlesonly: true
+---
+/autoapi/{{ cookiecutter.project_slug }}/index
+```
diff --git a/{{cookiecutter.project_slug}}/docs/source/changes.md b/{{cookiecutter.project_slug}}/docs/source/changes.md
index 4680c7c..be87067 100644
--- a/{{cookiecutter.project_slug}}/docs/source/changes.md
+++ b/{{cookiecutter.project_slug}}/docs/source/changes.md
@@ -1,6 +1,6 @@
-# Changes
-
-This is a record of all past {{ cookiecutter.project_slug }} releases and what went into
-them in reverse chronological order.
-
-## x.x.x - {% now 'local', '%Y' %}-xx-xx
+# Changes
+
+This is a record of all past {{ cookiecutter.project_slug }} releases and what went into
+them in reverse chronological order.
+
+## x.x.x - {% now 'local', '%Y' %}-xx-xx
diff --git a/{{cookiecutter.project_slug}}/docs/source/index.md b/{{cookiecutter.project_slug}}/docs/source/index.md
index 9a76d5e..de2601b 100644
--- a/{{cookiecutter.project_slug}}/docs/source/index.md
+++ b/{{cookiecutter.project_slug}}/docs/source/index.md
@@ -1,10 +1,10 @@
-# Welcome to {{ cookiecutter.project_name }}'s documentation!
-
-```{toctree}
----
-caption: 'Contents:'
-maxdepth: 1
----
-changes
-api
-```
+# Welcome to {{ cookiecutter.project_name }}'s documentation!
+
+```{toctree}
+---
+caption: 'Contents:'
+maxdepth: 1
+---
+changes
+api
+```

From 8bdb63bf84a45852618512a9034173f241cdaeb1 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Thu, 14 Apr 2022 11:05:48 +0200
Subject: [PATCH 12/12] Fix.

---
 docs/source/faq.md   | 41 +++++++++++++++++++++++++++++++++++++++++
 docs/source/index.md | 20 +++++++++++---------
 2 files changed, 52 insertions(+), 9 deletions(-)
 create mode 100644 docs/source/faq.md

diff --git a/docs/source/faq.md b/docs/source/faq.md
new file mode 100644
index 0000000..58d8eb2
--- /dev/null
+++ b/docs/source/faq.md
@@ -0,0 +1,41 @@
+# FAQ
+
+Q: Why are the source files nested in `src/<project_slug>`?
+
+A: This is called the src layout and the advantages are discussed in this
+[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+
+Although the article discusses the src layout in terms of Python packages, it is also
+beneficial to structure a project the same way. Next to the reasons discussed there, it
+is possible to use a single Python environment for multiple projects without messing
+with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
+import modules.
+
+Q: My project is a Python package, but it does not seem to have a version. Where is it?
+
+A: The cookiecutter uses [setuptools_scm](https://github.com/pypa/setuptools_scm/) to
+manage the version number. When you install your created project as a Python package
+with `pip install -e .`, setuptools_scm tries to infer the version number from the tags
+created on the repo.
+
+For example, if you have switched to a commit associated with the tag `v0.2.0`,
+setuptools_scm will create a `src/<package_slug>/_version.py` with a variable containing
+`version = '0.2.0'` which you can use in your `src/<package_slug>/__init__.py`. If you
+are one commit ahead of the tag, you version will be something like `0.2.0.dev1+...`
+indicating you are one commit ahead of the tag `v0.2.0`.
+
+If you want to switch to the tradition setup, replace the following code in your
+`pyproject.toml`
+
+```toml
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]
+```
+
+with
+
+```toml
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+```
diff --git a/docs/source/index.md b/docs/source/index.md
index 4e50a38..ffb6e99 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -26,24 +26,26 @@ Then, set up the template with
 $ cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
 ```
 
-## FAQ
+## Documentation
 
-Q: Why are the source files nested in `src/<project_slug>`?
+If you are new to pytask, just follow the
+[tutorials](https://pytask-dev.readthedocs.io/en/stable/tutorials/index.html) which will
+help you with your first steps like how to write the first task.
 
-A: This is called the src layout and the advantages are discussed in this
-[article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/).
+If you are already familiar with pytask, the
+[how-to guides](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/index.html)
+offer more in-depth guidance on complex projects.
 
-Although the article discusses the src layout in terms of Python packages, it is also
-beneficial to structure a project the same way. Next to the reasons discussed there, it
-is possible to use a single Python environment for multiple projects without messing
-with your PYTHONPATH (via `pip install -e .` or `conda develop .`) each time and still
-import modules.
+In general, you will find most guidance in the
+[documentation](https://pytask-dev.readthedocs.io/en/stable/index.html) and some advice
+in the FAQ below.
 
 ```{toctree}
 ---
 caption: 'Contents:'
 maxdepth: 1
 ---
+faq
 changes
 api
 ```