docs: mkdocs and github pages support (#1018)

* refactor: Migrate documentation to MkDocs with material theme and improved structure

* refactor: docs images hierarchy

* refactor: Move screenshots to assets and update paths in Screenshots.md

* feat: Convert screenshots to MkDocs content tabs with light/dark theme switching

* feat: sync content tabs by label

* chore: add light theme with shiori red color

* docs: Update index page to match README with concise feature list

* docs: Remove Resources section from documentation index

* ci: added github workflows

* docs: Add section for building documentation in Contribute.md

.github/workflows/_mkdocs-check.yml

@@ -0,0 +1,17 @@
+name: "Check mkdocs documentation"
+
+on: workflow_call
+
+jobs:
+  mkdocs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@24cb9080177205b6e8c946b17badbe402adc938f # v3.4.0
+
+      - name: Set up Python
+        uses: actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1 # v4.7.0
+
+      - name: check
+        run: make docs
+        env:
+          MKDOCS_EXTRA_FLAGS: --strict

.github/workflows/_mkdocs-publish.yml

@@ -0,0 +1,19 @@
+name: "Publish documentation"
+
+on: workflow_call
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@24cb9080177205b6e8c946b17badbe402adc938f # v3.4.0
+
+      - name: Set up Python
+        uses: actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1 # v4.7.0
+
+      - run: make docs
+        env:
+          DOCS_COMMAND: publish

.github/workflows/pull_request.yml

@@ -18,10 +18,12 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN}}
   call-swagger-check:
     uses: ./.github/workflows/_swagger-check.yml
+  call-mkdocs-check:
+    uses: ./.github/workflows/_mkdocs-check.yml
   call-styles-check:
     uses: ./.github/workflows/_styles-check.yml
   call-e2e:
-    needs: [call-lint, call-test, call-swagger-check, call-styles-check]
+    needs: [call-lint, call-test, call-swagger-check, call-styles-check, call-mkdocs-check]
     uses: ./.github/workflows/_e2e.yml
   call-gorelease:
     needs: [call-e2e]

.github/workflows/version_bump.yml

@@ -44,3 +44,6 @@ jobs:
     with:
       tag_prefix: alpine-
       dockerfile: Dockerfile.alpine
+  call-mkdocs-publish:
+    needs: [call-buildx, call-buildx-alpine]
+    uses: ./.github/workflows/_mkdocs-publish.yml

.gitignore

@@ -28,3 +28,7 @@ go.work*
 
 # workaround for buildx using podman
 type=docker
+
+# Docs
+docs/.venv
+build/docs

docs/Contribute.md

@@ -80,3 +80,17 @@ Finally, run the tests with the following command:
 ```bash
 make unittest
 ```
+
+## Building the documentation
+
+The documentation is built using MkDocs with the Material theme. For installation instructions, please refer to the [MkDocs installation guide](https://www.mkdocs.org/user-guide/installation/).
+
+To preview the documentation locally while making changes, run:
+
+```bash
+mkdocs serve
+```
+
+This will start a local server at `http://127.0.0.1:8000` where you can preview your changes in real-time.
+
+Documentation for production is generated automatically on every release and published using github pages.

docs/Screenshots.md

@@ -1,139 +1,67 @@
-Desktop
----
+# Desktop Screenshots
 
-<table style="width:100%">
-    <tr align="center">
-        <td colspan="2">
-            <b>Login screen</b>
-        </td>
-    </tr>
-    <tr valign="top" align="center">
-        <td width="50%">
-            <a href="./screenshots/01-login.png">
-                <img src="./screenshots/01-login.png">
-            </a>
-        </td>
-        <td width="50%">
-            <a href="./screenshots/05-dark-login.png">
-                <img src="./screenshots/05-dark-login.png">
-            </a>
-        </td>
-    </tr>
-    <tr align="center">
-        <td colspan="2">
-            <b>Grid mode</b>
-        </td>
-    </tr>
-    <tr valign="top" align="center">
-        <td width="50%">
-            <a href="./screenshots/02-home.png">
-                <img src="./screenshots/02-home.png">
-            </a>
-        </td>
-        <td width="50%">
-            <a href="./screenshots/06-dark-home.png">
-                <img src="./screenshots/06-dark-home.png">
-            </a>
-        </td>
-    </tr>
-    <tr align="center">
-        <td colspan="2">
-            <b>List mode</b>
-        </td>
-    </tr>
-    <tr valign="top" align="center">
-        <td width="50%">
-            <a href="./screenshots/03-home-list.png">
-                <img src="./screenshots/03-home-list.png">
-            </a>
-        </td>
-        <td width="50%">
-            <a href="./screenshots/07-dark-home-list.png">
-                <img src="./screenshots/07-dark-home-list.png">
-            </a>
-        </td>
-    </tr>
-    <tr align="center">
-        <td colspan="2">
-            <b>Options page</b>
-        </td>
-    </tr>
-    <tr valign="top" align="center">
-        <td width="50%">
-            <a href="./screenshots/04-options.png">
-                <img src="./screenshots/04-options.png">
-            </a>
-        </td>
-        <td width="50%">
-            <a href="./screenshots/08-dark-options.png">
-                <img src="./screenshots/08-dark-options.png">
-            </a>
-        </td>
-    </tr>
-</table>
+## Login Screen
 
-Mobile
-------
+=== "Light Theme"
+    [![Login Screen Light](../assets/screenshots/01-login.png)](../assets/screenshots/01-login.png)
 
-<table style="width:100%">
-    <tr align="center">
-        <td colspan="2">
-            <b>Login screen</b>
-        </td>
-        <td colspan="2">
-            <b>Grid mode</b>
-        </td>
-    </tr>
-    <tr valign="top" align="center">
-        <td width="25%">
-            <a href="./screenshots/09-mobile-login.png">
-                <img src="./screenshots/09-mobile-login.png">
-            </a>
-        </td>
-        <td width="25%">
-            <a href="./screenshots/13-mobile-dark-login.png">
-                <img src="./screenshots/13-mobile-dark-login.png">
-            </a>
-        </td>
-        <td width="25%">
-            <a href="./screenshots/10-mobile-home.png">
-                <img src="./screenshots/10-mobile-home.png">
-            </a>
-        </td>
-        <td width="25%">
-            <a href="./screenshots/14-mobile-dark-home.png">
-                <img src="./screenshots/14-mobile-dark-home.png">
-            </a>
-        </td>
-    </tr>
-    <tr align="center">
-        <td colspan="2">
-            <b>List mode</b>
-        </td>
-        <td colspan="2">
-            <b>Options page</b>
-        </td>
-    </tr>
-    <tr valign="top" align="center">
-        <td width="25%">
-            <a href="./screenshots/11-mobile-home-list.png">
-                <img src="./screenshots/11-mobile-home-list.png">
-            </a>
-        </td>
-        <td width="25%">
-            <a href="./screenshots/15-mobile-dark-home-list.png">
-                <img src="./screenshots/15-mobile-dark-home-list.png">
-            </a>
-        </td>
-        <td width="25%">
-            <a href="./screenshots/12-mobile-options.png">
-                <img src="./screenshots/12-mobile-options.png">
-            </a>
-        </td>
-        <td width="25%">
-            <a href="./screenshots/16-mobile-dark-options.png">
-                <img src="./screenshots/16-mobile-dark-options.png">
-            </a>
-        </td>
-    </tr>
-</table>
+=== "Dark Theme"
+    [![Login Screen Dark](../assets/screenshots/05-dark-login.png)](../assets/screenshots/05-dark-login.png)
+
+## Grid Mode
+
+=== "Light Theme"
+    [![Grid Mode Light](../assets/screenshots/02-home.png)](../assets/screenshots/02-home.png)
+
+=== "Dark Theme"
+    [![Grid Mode Dark](../assets/screenshots/06-dark-home.png)](../assets/screenshots/06-dark-home.png)
+
+## List Mode
+
+=== "Light Theme"
+    [![List Mode Light](../assets/screenshots/03-home-list.png)](../assets/screenshots/03-home-list.png)
+
+=== "Dark Theme"
+    [![List Mode Dark](../assets/screenshots/07-dark-home-list.png)](../assets/screenshots/07-dark-home-list.png)
+
+## Options Page
+
+=== "Light Theme"
+    [![Options Light](../assets/screenshots/04-options.png)](../assets/screenshots/04-options.png)
+
+=== "Dark Theme"
+    [![Options Dark](../assets/screenshots/08-dark-options.png)](../assets/screenshots/08-dark-options.png)
+
+# Mobile Screenshots
+
+## Login Screen
+
+=== "Light Theme"
+    [![Mobile Login Light](../assets/screenshots/09-mobile-login.png)](../assets/screenshots/09-mobile-login.png)
+
+=== "Dark Theme"
+    [![Mobile Login Dark](../assets/screenshots/13-mobile-dark-login.png)](../assets/screenshots/13-mobile-dark-login.png)
+
+## Grid Mode
+
+=== "Light Theme"
+    [![Mobile Grid Light](../assets/screenshots/10-mobile-home.png)](../assets/screenshots/10-mobile-home.png)
+
+=== "Dark Theme"
+    [![Mobile Grid Dark](../assets/screenshots/14-mobile-dark-home.png)](../assets/screenshots/14-mobile-dark-home.png)
+
+## List Mode
+
+=== "Light Theme"
+    [![Mobile List Light](../assets/screenshots/11-mobile-home-list.png)](../assets/screenshots/11-mobile-home-list.png)
+
+=== "Dark Theme"
+    [![Mobile List Dark](../assets/screenshots/15-mobile-dark-home-list.png)](../assets/screenshots/15-mobile-dark-home-list.png)
+
+## Options Page
+
+=== "Light Theme"
+    [![Mobile Options Light](../assets/screenshots/12-mobile-options.png)](../assets/screenshots/12-mobile-options.png)
+
+=== "Dark Theme"
+    [![Mobile Options Dark](../assets/screenshots/16-mobile-dark-options.png)](../assets/screenshots/16-mobile-dark-options.png)

docs/assets/css/style.css

@@ -0,0 +1,3 @@
+[data-md-color-scheme="shiori"] {
+    --md-primary-fg-color: rgb(244, 67, 54);
+}

docs/index.md

@@ -1,16 +1,10 @@
 # Documentation
 
-Shiori is a simple bookmarks manager written in Go language. Intended as a simple clone of [Pocket](https://getpocket.com/). You can use it as command line application or as web application. This application is distributed as a single binary, which means it can be installed and used easily.
+Shiori is a simple bookmarks manager written in Go language. Intended as a simple clone of [Pocket](https://getpocket.com/), it can be used as both a command line and web application. Features include:
 
-## Resources
-
-- [API](./API.md) (Deprecated)
-- [APIv1](./APIv1.md) ([What is this?](https://github.com/go-shiori/shiori/issues/640))
-- [Contributing](./Contribute.md)
-- [Command Line Interface](./CLI.md)
-- [Configuration](./Configuration.md)
-- [FAQ](./Frequently-Asked-Question.md)
-- [Installation](./Installation.md)
-- [Screenshots](./screenshots/)
-- [Storage](./Storage.md)
-- [Usage](./Usage.md)
+- Basic bookmarks management (add, edit, delete and search)
+- Import/export bookmarks from Netscape Bookmark file
+- Import from Pocket
+- Simple web interface
+- Offline webpage archiving
+- Support for SQLite, PostgreSQL and MySQL

mkdocs.yml

@@ -0,0 +1,54 @@
+site_name: Shiori Documentation
+site_description: Documentation for the Shiori bookmark manager
+repo_url: https://github.com/go-shiori/shiori
+theme:
+  name: material
+  palette:
+  # Light mode
+  - scheme: shiori
+    media: "(prefers-color-scheme: light)"
+    toggle:
+      icon: material/brightness-7
+      name: Switch to dark mode
+  # Dark mode
+  - scheme: slate
+    media: "(prefers-color-scheme: dark)"
+    toggle:
+      icon: material/brightness-4
+      name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.indexes
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+extra_css:
+  - assets/css/style.css
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: installation.md
+    - Usage: usage.md
+    - Configuration: configuration.md
+    - Storage: storage.md
+  - API Reference:
+    - API v1: apiv1.md
+    - Legacy API: api.md
+  - Contributing:
+    - Contributing Guide: contribute.md
+    - FAQ: faq.md
+  - Screenshots: screenshots.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - toc:
+      permalink: true