Merge pull request #2104 from paperless-ngx/docs-cleanup

Chore: Cleans up documentation links

docs/administration.md

@@ -9,7 +9,7 @@ Before making backups, make sure that paperless is not running.
 
 Options available to any installation of paperless:
 
-- Use the [document exporter](/administration#exporter). The document exporter exports all your documents,
+- Use the [document exporter](administration#exporter). The document exporter exports all your documents,
   thumbnails and metadata to a specific folder. You may import your
   documents into a fresh instance of paperless again or store your
   documents in another DMS with this export.
@@ -382,8 +382,7 @@ document_renamer
 The command takes no arguments and processes all your documents at once.
 
 Learn how to use
-`Management Utilities<utilities-management-commands>`{.interpreted-text
+[Management Utilities](#management-commands).
-role="ref"}.
 
 ### Sanity checker {#sanity-checker}
 

docs/api.md

@@ -162,8 +162,7 @@ specific query parameters cause the API to return full text search
 results:
 
 - `/api/documents/?query=your%20search%20query`: Search for a document
-  using a full text query. For details on the syntax, see
+  using a full text query. For details on the syntax, see [Basic Usage - Searching](usage#basic-usage_searching).
-  `basic-usage_searching`{.interpreted-text role="ref"}.
 - `/api/documents/?more_like=1234`: Search for documents similar to
   the document with id 1234.
 
@@ -232,7 +231,7 @@ Tf/Idf score in the index.
 ["term1", "term3", "term6", "term4"]
 ```
 
-## POSTing documents {#api-file_uploads}
+## POSTing documents {#file-uploads}
 
 The API provides a special endpoint for file uploads:
 

docs/configuration.md

@@ -45,8 +45,7 @@ database engine. Available options are [postgresql]{.title-ref} and
 
     !!! warning
 
-        Using MariaDB comes with some caveats. See
+        Using MariaDB comes with some caveats. See [MySQL Caveats](advanced_usage#mysql-caveats).
-        `advanced-mysql-caveats`{.interpreted-text role="ref"} for details.
 
 `PAPERLESS_DBHOST=<hostname>`
 
@@ -151,8 +150,7 @@ files created using "collectstatic" manager command are stored.
 `PAPERLESS_FILENAME_FORMAT=<format>`
 
 : Changes the filenames paperless uses to store documents in the media
-directory. See `advanced-file_name_handling`{.interpreted-text
+directory. See [File name handling](advanced_usage#file_name_handling) for details.
-role="ref"} for details.
 
     Default is none, which disables this feature.
 
@@ -161,8 +159,7 @@ role="ref"} for details.
 : Tells paperless to replace placeholders in
 [PAPERLESS_FILENAME_FORMAT]{.title-ref} that would resolve to
 'none' to be omitted from the resulting filename. This also holds
-true for directory names. See
+true for directory names. See [File name handling](advanced_usage#file_name_handling) for
-`advanced-file_name_handling`{.interpreted-text role="ref"} for
 details.
 
     Defaults to [false]{.title-ref} which disables this feature.
@@ -630,7 +627,7 @@ for indentation.
 Make sure to use the correct format [PAPERLESS_TIKA_ENABLED =
 1]{.title-ref} so python_dotenv can parse the statement correctly.
 
-## Software tweaks
+## Software tweaks {#software_tweaks}
 
 `PAPERLESS_TASK_WORKERS=<num>`
 
@@ -830,8 +827,7 @@ documents.
 
 : After a document is consumed, Paperless can trigger an arbitrary
 script if you like. This script will be passed a number of arguments
-for you to work with. For more information, take a look at
+for you to work with. For more information, take a look at [Post-consumption script](advanced_usage#post_consume_script).
-`advanced-post_consume_script`{.interpreted-text role="ref"}.
 
     The default is blank, which means nothing will be executed.
 
@@ -1021,9 +1017,7 @@ configuration option:
 [Flower](https://flower.readthedocs.io/en/latest/index.html) will be
 started by the container.
 
-    You can read more about this in the
+    You can read more about this in the [advanced documentation](advanced#celery-monitoring).
-    `advanced setup <advanced-celery-monitoring>`{.interpreted-text
-    role="ref"} documentation.
 
 ## Update Checking {#update-checking}
 

docs/faq.md

@@ -41,9 +41,8 @@ elsewhere. Here are a couple notes about that.
 - By default, paperless uses the internal ID of each document as its
   filename. This might not be very convenient for export. However, you
   can adjust the way files are stored in paperless by
-  `configuring the filename format <advanced-file_name_handling>`{.interpreted-text
+  [configuring the filename format](advanced_usage#file_name_handling).
-  role="ref"}.
+- [The exporter](administration#exporter) is
-- `The exporter <utilities-exporter>`{.interpreted-text role="ref"} is
   another easy way to get your files out of paperless with reasonable
   file names.
 
@@ -55,8 +54,7 @@ elsewhere. Here are a couple notes about that.
   are processed with OCR and converted into PDF documents.
 - Plain text documents are supported as well and are added verbatim to
   paperless.
-- With the optional Tika integration enabled (see
+- With the optional Tika integration enabled (see [Tika configuration](configuration#tika),
-  `Configuration <configuration-tika>`{.interpreted-text role="ref"}),
   Paperless also supports various Office documents (.docx, .doc, odt,
   .ppt, .pptx, .odp, .xls, .xlsx, .ods).
 
@@ -75,8 +73,7 @@ has to do much less work to serve the data.
 !!! note
 
     You can adjust some of the settings so that paperless uses less
-    processing power. See `setup-less_powerful_devices`{.interpreted-text
+    processing power. See [setup](setup#less_powerful_devices) for details.
-    role="ref"} for details.
 
 ### _How do I install paperless-ngx on Raspberry Pi?_
 
@@ -108,7 +105,7 @@ see if it works.
 
 ### _How do I proxy this with NGINX?_
 
-**A:** See `here <setup-nginx>`{.interpreted-text role="ref"}.
+**A:** See [here](setup#nginx).
 
 ### _How do I get WebSocket support with Apache mod_wsgi_?
 

docs/setup.md

@@ -23,8 +23,7 @@ Paperless provides an interactive installation script. This script will
 ask you for a couple configuration options, download and create the
 necessary configuration files, pull the docker image, start paperless
 and create your user account. This script essentially performs all the
-steps described in `setup-docker_hub`{.interpreted-text role="ref"}
+steps described in [Docker setup](#docker_hub) automatically.
-automatically.
 
 1.  Make sure that docker and docker-compose are installed.
 
@@ -36,17 +35,20 @@ automatically.
 
 ### From GHCR / Docker Hub {#docker_hub}
 
-1.  Login with your user and create a folder in your home-directory
+1.  Login with your user and create a folder in your home-directory to have a place for your
-    [mkdir -v \~/paperless-ngx]{.title-ref} to have a place for your
     configuration files and consumption directory.
 
+    ```shell-session
+    $ mkdir -v ~/paperless-ngx
+    ```
+
 2.  Go to the [/docker/compose directory on the project
     page](https://github.com/paperless-ngx/paperless-ngx/tree/master/docker/compose)
-    and download one of the [docker-compose.\*.yml]{.title-ref} files,
+    and download one of the `docker-compose.*.yml` files,
     depending on which database backend you want to use. Rename this
-    file to [docker-compose.yml]{.title-ref}. If you want to enable
+    file to `docker-compose.*.yml`. If you want to enable
     optional support for Office documents, download a file with
-    [-tika]{.title-ref} in the file name. Download the
+    `-tika` in the file name. Download the
     `docker-compose.env` file and the `.env` file as well and store them
     in the same directory.
 
@@ -62,27 +64,27 @@ automatically.
 
         If you want to use the included `docker-compose.*.yml` file, you
         need to have at least Docker version **17.09.0** and docker-compose
-        version **1.17.0**. To check do: [docker-compose -v]{.title-ref} or
+        version **1.17.0**. To check do: `docker-compose -v` or
-        [docker -v]{.title-ref}
+        `docker -v`
 
-        See the [Docker installation guide]() on how to install the current
+        See the [Docker installation guide](https://docs.docker.com/engine/install/) on how to install the current
         version of Docker for your operating system or Linux distribution of
         choice. To get the latest version of docker-compose, follow the
-        [docker-compose installation guide]() if your package repository
+        [docker-compose installation guide](https://docs.docker.com/compose/install/linux/) if your package repository
         doesn't include it.
 
 4.  Modify `docker-compose.yml` to your preferences. You may want to
     change the path to the consumption directory. Find the line that
     specifies where to mount the consumption directory:
 
-    ```
+    ```yaml
     - ./consume:/usr/src/paperless/consume
     ```
 
     Replace the part BEFORE the colon with a local directory of your
     choice:
 
-    ```
+    ```yaml
     - /home/jonaswinkler/paperless-inbox:/usr/src/paperless/consume
     ```
 
@@ -92,17 +94,17 @@ automatically.
     You may also need to change the default port that the webserver will
     use from the default (8000):
 
-    > ```
+    ```yaml
-    > ports:
+    ports:
-    >   - 8000:8000
+      - 8000:8000
-    > ```
+    ```
 
     Replace the part BEFORE the colon with a port of your choice:
 
-    > ```
+    ```yaml
-    > ports:
+    ports:
-    >   - 8010:8000
+      - 8010:8000
-    > ```
+    ```
 
     Don't change the part after the colon or edit other lines that
     refer to port 8000. Modifying the part before the colon will map
@@ -137,27 +139,26 @@ automatically.
     machine have write access to the consumption directory. If your UID
     and GID on the host system is 1000 (the default for the first normal
     user on most systems), it will work out of the box without any
-    modifications. [id "username"]{.title-ref} to check.
+    modifications. `id "username"` to check.
 
     !!! note
 
         You can copy any setting from the file `paperless.conf.example` and
-        paste it here. Have a look at `configuration`{.interpreted-text
+        paste it here. Have a look at [configuration](/configuration] to see what's available.
-        role="ref"} to see what's available.
 
     !!! note
 
         You can utilize Docker secrets for some configuration settings by
-        appending [\_FILE]{.title-ref} to some configuration values. This is
+        appending `_FILE` to some configuration values. This is
         supported currently only by:
 
-        -   PAPERLESS_DBUSER
+        - PAPERLESS_DBUSER
-        -   PAPERLESS_DBPASS
+        - PAPERLESS_DBPASS
-        -   PAPERLESS_SECRET_KEY
+        - PAPERLESS_SECRET_KEY
-        -   PAPERLESS_AUTO_LOGIN_USERNAME
+        - PAPERLESS_AUTO_LOGIN_USERNAME
-        -   PAPERLESS_ADMIN_USER
+        - PAPERLESS_ADMIN_USER
-        -   PAPERLESS_ADMIN_MAIL
+        - PAPERLESS_ADMIN_MAIL
-        -   PAPERLESS_ADMIN_PASSWORD
+        - PAPERLESS_ADMIN_PASSWORD
 
     !!! warning
 
@@ -233,7 +234,7 @@ automatically.
         certain, more updated software. If you want to build these images
         your self, that is possible, but beyond the scope of these steps.
 
-4.  Follow steps 3 to 8 of `setup-docker_hub`{.interpreted-text
+4.  Follow steps 3 to 8 of [Docker Setup](setup#docker_hub)
     role="ref"}. When asked to run `docker-compose pull` to pull the
     image, do
 
@@ -320,9 +321,9 @@ supported.
     by yourself. Extract the archive to a place from where you wish to
     execute it, such as `/opt/paperless`.
 
-5.  Configure paperless. See `configuration`{.interpreted-text
+5.  Configure paperless. See [configuration](configuration) for details.
-    role="ref"} for details. Edit the included `paperless.conf` and
+    Edit the included `paperless.conf` and adjust the settings to your
-    adjust the settings to your needs. Required settings for getting
+    needs. Required settings for getting
     paperless running are:
 
     - `PAPERLESS_REDIS` should point to your redis server, such as
@@ -343,7 +344,7 @@ supported.
       allows third parties to forge authentication credentials.
     - `PAPERLESS_URL` if you are behind a reverse proxy. This should
       point to your domain. Please see
-      `configuration`{.interpreted-text role="ref"} for more
+      [configuration](configuration) for more
       information.
 
     Many more adjustments can be made to paperless, especially the OCR
@@ -479,8 +480,8 @@ supported.
     not available for most distributions.
 
 15. Optional: If using the NLTK machine learning processing (see
-    `PAPERLESS_ENABLE_NLTK` in `configuration`{.interpreted-text
+    `PAPERLESS_ENABLE_NLTK` in [configuration](configuration#software_tweaks) for details),
-    role="ref"} for details), download the NLTK data for the Snowball
+    download the NLTK data for the Snowball
     Stemmer, Stopwords and Punkt tokenizer to your
     `PAPERLESS_DATA_DIR/nltk`. Refer to the [NLTK
     instructions](https://www.nltk.org/data.html) for details on how to
@@ -531,8 +532,8 @@ installation. The important things to keep in mind are as follows:
 - Read the [changelog](/changelog) and
   take note of breaking changes.
 - You should decide if you want to stick with SQLite or want to
-  migrate your database to PostgreSQL. See
+  migrate your database to PostgreSQL. See [documentation](#sqlite_to_psql)
-  `setup-sqlite_to_psql`{.interpreted-text role="ref"} for details on
+  for details on
   how to move your data from SQLite to PostgreSQL. Both work fine with
   paperless. However, if you already have a database server running
   for other services, you might as well use it for paperless as well.
@@ -585,7 +586,7 @@ Migration to paperless-ngx is then performed in a few simple steps:
     after you migrated your existing SQLite database.
 
 5.  Adjust `docker-compose.yml` and `docker-compose.env` to your needs.
-    See `setup-docker_hub`{.interpreted-text role="ref"} for details on
+    See [Docker setup](setup#docker_hub) details on
     which edits are advised.
 
 6.  [Update paperless.](/administration#updating)
@@ -675,8 +676,12 @@ below use PostgreSQL, but are applicable to MySQL/MariaDB with the
 !!! warning
 
     MySQL is case insensitive by default, treating values like "Name" and
-    "NAME" as identical. See `advanced-mysql-caveats`{.interpreted-text
+    "NAME" as identical. See [MySQL caveats](advanced##mysql-caveats) for details.
-    role="ref"} for details.
+
+!!! warning
+
+    MySQL also enforces limits on maximum lengths, but does so differently than
+    PostgreSQL.  It may not be possible to migrate to MySQL due to this.
 
 1.  Stop paperless, if it is running.
 
@@ -686,7 +691,7 @@ below use PostgreSQL, but are applicable to MySQL/MariaDB with the
     file to `docker-compose.yml`. Remember to adjust the consumption
     directory, if necessary.
     b) Without docker, configure the database in your `paperless.conf`
-    file. See `configuration`{.interpreted-text role="ref"} for
+    file. See [configuration](configuration) for
     details.
 
 3.  Open a shell and initialize the database:
@@ -792,7 +797,7 @@ performance immensely:
   more advanced language processing, which can take more memory and
   processing time.
 
-For details, refer to `configuration`{.interpreted-text role="ref"}.
+For details, refer to [configuration](configuration).
 
 !!! note
 
@@ -844,8 +849,7 @@ http {
 ```
 
 The `PAPERLESS_URL` configuration variable is also required when using a
-reverse proxy. Please refer to the
+reverse proxy. Please refer to the [hosting and security](configuration#hosting-and-security) docs.
-`hosting-and-security`{.interpreted-text role="ref"} docs.
 
 Also read
 [this](https://channels.readthedocs.io/en/stable/deploying.html#nginx-supervisor-ubuntu),

docs/troubleshooting.md

@@ -145,8 +145,7 @@ The following error occured while consuming document.pdf: [Errno 13] Permission
 This happens when paperless does not have permission to delete files
 inside the consumption directory. Ensure that `USERMAP_UID` and
 `USERMAP_GID` are set to the user id and group id you use on the host
-operating system, if these are different from `1000`. See
+operating system, if these are different from `1000`. See [Docker setup](setup#docker_hub).
-`setup-docker_hub`{.interpreted-text role="ref"}.
 
 Also ensure that you are able to read and write to the consumption
 directory on the host.

docs/usage.md

@@ -37,7 +37,7 @@ Each document has a couple of fields that you can assign to them:
   date you signed a contract, or the date a letter was sent to you.
 - The _archive serial number_ (short: ASN) of a document is the
   identifier of the document in your physical document binders. See
-  `usage-recommended_workflow`{.interpreted-text role="ref"} below.
+  [recommended workflow](#usage-reccomended_workflow) below.
 - The _content_ of a document is the text that was OCR'ed from the
   document. This text is fed into the search engine and is used for
   matching tags, correspondents and document types.
@@ -195,8 +195,8 @@ configured on the 'Scheduled tasks' page in the admin.
 
 ### REST API
 
-You can also submit a document using the REST API, see
+You can also submit a document using the REST API, see [docs][api#file-uploads]
-`api-file_uploads`{.interpreted-text role="ref"} for details.
+for details.
 
 ## Best practices {#basic-searching}
 
@@ -398,7 +398,7 @@ Once you have scanned in a document, proceed in paperless as follows.
     paperless will assign them automatically. After consuming a couple
     documents, you can even ask paperless to *learn* when to assign tags and
     correspondents by itself. For details on this feature, see
-    `advanced-matching`{.interpreted-text role="ref"}.
+    [advanced matching](advanced_usage#matching).
 
 ### Task management