Merge pull request #1167 from virtualtam/mkdocs

Improve Mkdocs build process, fix formatting issues

9 files changed, 47 insertions, 25 deletions

diff --git a/.travis.yml b/.travis.yml
index eee1ca74..cb81846f 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -28,6 +28,15 @@ matrix:
         - yarn run build # Just to be sure that the build isn't broken
         - make eslint
         - make sasslint
+    - language: python
+      python: 3.6
+      cache:
+        directories:
+          - $HOME/.cache/pip
+      install:
+        - pip install mkdocs
+      script:
+        - mkdocs build --clean
 
 cache:
   directories:
diff --git a/Dockerfile b/Dockerfile
index 4cda6f31..cb835ced 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,7 +5,7 @@ FROM python:3-alpine as docs
 ADD . /usr/src/app/shaarli
 RUN cd /usr/src/app/shaarli \
     && pip install --no-cache-dir mkdocs \
-    && mkdocs build
+    && mkdocs build --clean
 
 # Stage 2:
 # - Resolve PHP dependencies with Composer
diff --git a/Makefile b/Makefile
index 4adbdd68..b0cdadf0 100644
--- a/Makefile
+++ b/Makefile
@@ -207,7 +207,7 @@ htmldoc:
         python3 -m venv venv/
         bash -c 'source venv/bin/activate; \
         pip install mkdocs; \
-        mkdocs build'
+        mkdocs build --clean'
         find doc/html/ -type f -exec chmod a-x '{}' \;
         rm -r venv
 
diff --git a/doc/md/FAQ.md b/doc/md/FAQ.md
index 77faf117..a2ec7d57 100644
--- a/doc/md/FAQ.md
+++ b/doc/md/FAQ.md
@@ -22,7 +22,9 @@ With Shaarli:
 Shaarli stands for _shaaring_ your _links_.
 
 ### My Shaarli is broken!
-First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
+First of all, ensure that both the [web server](Server-configuration) and
+[Shaarli](Shaarli-configuration) are correctly configured, and that your
+installation is [supported](Server-configuration).
 
 If everything looks right but the issue(s) remain(s), please:
 
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
index 68a83c00..c016de56 100644
--- a/doc/md/REST-API.md
+++ b/doc/md/REST-API.md
@@ -3,8 +3,9 @@
 See the [REST API documentation](http://shaarli.github.io/api-documentation/)
 for a list of available endpoints and parameters.
 
-Please ensure that your server meets the [requirements](Server-requirements)
-and is properly [configured](Server-configuration):
+Please ensure that your server meets the
+[requirements](Server-configuration#prerequisites) and is properly
+[configured](Server-configuration):
 
 - URL rewriting is enabled (see specific Apache and Nginx sections)
 - the server's timezone is properly defined
diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md
index faacc1f9..4910ff6c 100644
--- a/doc/md/Sharing-content.md
+++ b/doc/md/Sharing-content.md
@@ -1,4 +1,4 @@
-Content posted to Shaarli is separated in items called _Shaares_. For each Shaare, 
+Content posted to Shaarli is separated in items called _Shaares_. For each Shaare,
 you can customize the following aspects:
 
  * URL to link to
@@ -13,10 +13,10 @@ you can customize the following aspects:
 
 While logged in to your Shaarli, you can add new Shaares in several ways:
 
- * [+Shaare button]
- * [Bookmarklet]
+ * [+Shaare button](#shaare-button)
+ * [Bookmarklet](#bookmarklet)
  * [Firefox Share](#firefox-share)
- * Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps)
+ * Third-party [apps and browser addons](Community-&-Related-software.md#mobile-apps)
  * [REST API](https://shaarli.github.io/api-documentation/)
 
 ### +Shaare button
@@ -33,14 +33,14 @@ While logged in to your Shaarli, you can add new Shaares in several ways:
 
 ### Bookmarklet
 
-The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special 
-browser bookmark you can use to add new content to your Shaarli. This bookmarklet is 
+The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special
+browser bookmark you can use to add new content to your Shaarli. This bookmarklet is
 compatible with Firefox, Opera, Chrome and Safari. To set it up:
 
  * Access the `Tools` page from the button in the toolbar.
  * Drag the **`✚Shaare link` button** to your browser's bookmarks bar.
 
-Once this is done, you can shaare any URL you are visiting simply by clicking the 
+Once this is done, you can shaare any URL you are visiting simply by clicking the
 bookmarklet in your browser! The same `New Shaare` dialog as above is displayed.
 
 | Note | Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunately, there is nothing Shaarli can do about it. \[[1](https://github.com/shaarli/Shaarli/issues/196)]\ \[[2](https://bugzilla.mozilla.org/show_bug.cgi?id=866522)]\ \[[3](https://code.google.com/p/chromium/issues/detail?id=233903)]\ |
@@ -59,8 +59,8 @@ Before using Firefox Share, you must first add Shaarli as a sharing provider:
 - Click the `Tools` button in the top bar
 - Click the `✚Add to Firefox social` button and accept the activation.
 
-Once this is done, you can share any URL you are visiting by clicking the Firefox 
-_Share_ button [images/firefoxshare.png](images/firefoxshare.png)
+Once this is done, you can share any URL you are visiting by clicking the Firefox
+_Share_ button ![images/firefoxshare.png](images/firefoxshare.png)
 
 | Note | Firefox Share is no longer available for Firefox 57 and later versions. |
 |---------|---------|
@@ -74,15 +74,15 @@ _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
 
 Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button.
 
-Editing a Shaare will not change it's permalink, each permalink always points to the 
+Editing a Shaare will not change it's permalink, each permalink always points to the
 latest revision of a Shaare.
 
 --------------------------------------------------------------------------------
 
 ## Using shaarli as a blog, notepad, pastebin...
 
-While adding or editing a link, leave the URL field blank to create a text-only 
-("note") post. This allows you to post any kind of text content, such as blog 
-articles, private or public notes, snippets... There is no character limit! You can 
+While adding or editing a link, leave the URL field blank to create a text-only
+("note") post. This allows you to post any kind of text content, such as blog
+articles, private or public notes, snippets... There is no character limit! You can
 access your Shaare from its permalink.
 
diff --git a/doc/md/index.md b/doc/md/index.md
index 21a63d3c..c18332b4 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -6,7 +6,7 @@ Do you want to share the links you discover?
 Shaarli is a minimalist link sharing service that you can install on your own server.
 It is designed to be personal (single-user), fast and handy.
 
-<!--- TODO screenshots --->
+<!-- TODO screenshots -->
 
 Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
 For general information, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
@@ -30,7 +30,7 @@ It runs the latest development version of Shaarli and is updated/reset daily.
 
 Login: `demo`; Password: `demo`
 
-<!---- TODO review everything below this point --->
+<!-- TODO review everything below this point -->
 
 
 ## Features
@@ -98,7 +98,7 @@ Shaarli can be used:
 - bruteforce protection on the login form
 - protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking
 
-<!---- TODO Limitations --->
+<!-- TODO Limitations -->
 
 ### REST API
 
@@ -116,12 +116,17 @@ This is a community fork of the original [Shaarli](https://github.com/sebsauvage
 
 The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) that he would have no time to work on Shaarli in the near future.
 
-The Shaarli community has carried on the work to provide [many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
+The Shaarli community has carried on the work to provide [many
+patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for
+[bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+)
+in this repository, and will keep maintaining the project for the foreseeable
+future, while keeping Shaarli simple and efficient.
 
 
 ### Contributing
 
 If you'd like to help, please:
+
 - have a look at the open [issues](https://github.com/shaarli/Shaarli/issues)
 and [pull requests](https://github.com/shaarli/Shaarli/pulls)
 - feel free to report bugs (feedback is much appreciated)
@@ -132,5 +137,9 @@ and [pull requests](https://github.com/shaarli/Shaarli/pulls)
 
 ### License
 
-Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail of the contributors and licenses for each individual component. A list of contributors is available [here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS).
+Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See
+[COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail
+of the contributors and licenses for each individual component. A list of
+contributors is available
+[here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS).
 
diff --git a/index.php b/index.php
index 89b181cb..ddd5dbf5 100644
--- a/index.php
+++ b/index.php
@@ -48,7 +48,7 @@ if (! file_exists(__DIR__ . '/vendor/autoload.php')) {
         ."If you installed Shaarli through Git or using the development branch,\n"
         ."please refer to the installation documentation to install PHP"
         ." dependencies using Composer:\n"
-        ."- https://shaarli.readthedocs.io/en/master/Server-requirements/\n"
+        ."- https://shaarli.readthedocs.io/en/master/Server-configuration/\n"
         ."- https://shaarli.readthedocs.io/en/master/Download-and-Installation/";
     exit;
 }
diff --git a/mkdocs.yml b/mkdocs.yml
index f7828611..a1226e8f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,6 +5,7 @@ site_description: The personal, minimalist, super-fast, database free, bookmarki
 theme: readthedocs
 docs_dir: doc/md
 site_dir: doc/html
+strict: true
 
 pages:
 - Home: index.md
@@ -23,7 +24,7 @@ pages:
 - Usage:
     - Browsing and searching: Browsing-and-searching.md
     - Sharing content: Sharing-content.md
-    - RSS feeds: RSS-feeds.md 
+    - RSS feeds: RSS-feeds.md
     - REST API: REST-API.md
     - Community & Related software: Community-&-Related-software.md
 - How To: