Merge pull request #1167 from virtualtam/mkdocs

Improve Mkdocs build process, fix formatting issues

.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:

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

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
 

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:
 

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)
+Please ensure that your server meets the
-and is properly [configured](Server-configuration):
+[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

doc/md/Sharing-content.md

@@ -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]
+ * [+Shaare button](#shaare-button)
- * [Bookmarklet]
+ * [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
@@ -60,7 +60,7 @@ Before using Firefox Share, you must first add Shaarli as a sharing provider:
 - 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)
+_Share_ button ![images/firefoxshare.png](images/firefoxshare.png)
 
 | Note | Firefox Share is no longer available for Firefox 57 and later versions. |
 |---------|---------|

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).
 

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;
 }

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