From bb7bfcc2c20709945ecc04cbdad74ff89963c81c Mon Sep 17 00:00:00 2001
From: Felipe Martin <812088+fmartingr@users.noreply.github.com>
Date: Sun, 8 Dec 2024 15:11:32 +0100
Subject: [PATCH] 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 | 17 ++
.github/workflows/_mkdocs-publish.yml | 19 ++
.github/workflows/pull_request.yml | 4 +-
.github/workflows/version_bump.yml | 3 +
.gitignore | 4 +
docs/Contribute.md | 14 ++
docs/Screenshots.md | 206 ++++++------------
docs/assets/css/style.css | 3 +
docs/{ => assets}/screenshots/01-login.png | Bin
docs/{ => assets}/screenshots/02-home.png | Bin
.../{ => assets}/screenshots/03-home-list.png | Bin
docs/{ => assets}/screenshots/04-options.png | Bin
.../screenshots/05-dark-login.png | Bin
.../{ => assets}/screenshots/06-dark-home.png | Bin
.../screenshots/07-dark-home-list.png | Bin
.../screenshots/08-dark-options.png | Bin
.../screenshots/09-mobile-login.png | Bin
.../screenshots/10-mobile-home.png | Bin
.../screenshots/11-mobile-home-list.png | Bin
.../screenshots/12-mobile-options.png | Bin
.../screenshots/13-mobile-dark-login.png | Bin
.../screenshots/14-mobile-dark-home.png | Bin
.../screenshots/15-mobile-dark-home-list.png | Bin
.../screenshots/16-mobile-dark-options.png | Bin
.../screenshots}/comparison.png | Bin
docs/{readme => assets/screenshots}/cover.png | Bin
docs/{Frequently-Asked-Question.md => faq.md} | 0
docs/index.md | 20 +-
mkdocs.yml | 54 +++++
29 files changed, 191 insertions(+), 153 deletions(-)
create mode 100644 .github/workflows/_mkdocs-check.yml
create mode 100644 .github/workflows/_mkdocs-publish.yml
create mode 100644 docs/assets/css/style.css
rename docs/{ => assets}/screenshots/01-login.png (100%)
rename docs/{ => assets}/screenshots/02-home.png (100%)
rename docs/{ => assets}/screenshots/03-home-list.png (100%)
rename docs/{ => assets}/screenshots/04-options.png (100%)
rename docs/{ => assets}/screenshots/05-dark-login.png (100%)
rename docs/{ => assets}/screenshots/06-dark-home.png (100%)
rename docs/{ => assets}/screenshots/07-dark-home-list.png (100%)
rename docs/{ => assets}/screenshots/08-dark-options.png (100%)
rename docs/{ => assets}/screenshots/09-mobile-login.png (100%)
rename docs/{ => assets}/screenshots/10-mobile-home.png (100%)
rename docs/{ => assets}/screenshots/11-mobile-home-list.png (100%)
rename docs/{ => assets}/screenshots/12-mobile-options.png (100%)
rename docs/{ => assets}/screenshots/13-mobile-dark-login.png (100%)
rename docs/{ => assets}/screenshots/14-mobile-dark-home.png (100%)
rename docs/{ => assets}/screenshots/15-mobile-dark-home-list.png (100%)
rename docs/{ => assets}/screenshots/16-mobile-dark-options.png (100%)
rename docs/{readme => assets/screenshots}/comparison.png (100%)
rename docs/{readme => assets/screenshots}/cover.png (100%)
rename docs/{Frequently-Asked-Question.md => faq.md} (100%)
create mode 100644 mkdocs.yml
diff --git a/.github/workflows/_mkdocs-check.yml b/.github/workflows/_mkdocs-check.yml
new file mode 100644
index 000000000..6a3bebfea
--- /dev/null
+++ b/.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
diff --git a/.github/workflows/_mkdocs-publish.yml b/.github/workflows/_mkdocs-publish.yml
new file mode 100644
index 000000000..3933f9b50
--- /dev/null
+++ b/.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
diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
index a71adf146..1c422b981 100644
--- a/.github/workflows/pull_request.yml
+++ b/.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]
diff --git a/.github/workflows/version_bump.yml b/.github/workflows/version_bump.yml
index 891886f34..cbe29dc32 100644
--- a/.github/workflows/version_bump.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index fbda15183..a89d1170b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,3 +28,7 @@ go.work*
# workaround for buildx using podman
type=docker
+
+# Docs
+docs/.venv
+build/docs
diff --git a/docs/Contribute.md b/docs/Contribute.md
index 96a9748dd..ca0d7c65b 100644
--- a/docs/Contribute.md
+++ b/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.
diff --git a/docs/Screenshots.md b/docs/Screenshots.md
index 83393fbc8..673a85df9 100644
--- a/docs/Screenshots.md
+++ b/docs/Screenshots.md
@@ -1,139 +1,67 @@
-Desktop
----
-
-
-
- |
- Login screen
- |
-
-
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- |
- Grid mode
- |
-
-
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- |
- List mode
- |
-
-
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- |
- Options page
- |
-
-
-
-
- 
-
- |
-
-
- 
-
- |
-
-
-
-Mobile
-------
-
-
-
- |
- Login screen
- |
-
- Grid mode
- |
-
-
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- |
- List mode
- |
-
- Options page
- |
-
-
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- 
-
- |
-
-
- 
-
- |
-
-
+# Desktop Screenshots
+
+## Login Screen
+
+=== "Light Theme"
+ [](../assets/screenshots/01-login.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/05-dark-login.png)
+
+## Grid Mode
+
+=== "Light Theme"
+ [](../assets/screenshots/02-home.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/06-dark-home.png)
+
+## List Mode
+
+=== "Light Theme"
+ [](../assets/screenshots/03-home-list.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/07-dark-home-list.png)
+
+## Options Page
+
+=== "Light Theme"
+ [](../assets/screenshots/04-options.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/08-dark-options.png)
+
+# Mobile Screenshots
+
+## Login Screen
+
+=== "Light Theme"
+ [](../assets/screenshots/09-mobile-login.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/13-mobile-dark-login.png)
+
+## Grid Mode
+
+=== "Light Theme"
+ [](../assets/screenshots/10-mobile-home.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/14-mobile-dark-home.png)
+
+## List Mode
+
+=== "Light Theme"
+ [](../assets/screenshots/11-mobile-home-list.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/15-mobile-dark-home-list.png)
+
+## Options Page
+
+=== "Light Theme"
+ [](../assets/screenshots/12-mobile-options.png)
+
+=== "Dark Theme"
+ [](../assets/screenshots/16-mobile-dark-options.png)
diff --git a/docs/assets/css/style.css b/docs/assets/css/style.css
new file mode 100644
index 000000000..db8296483
--- /dev/null
+++ b/docs/assets/css/style.css
@@ -0,0 +1,3 @@
+[data-md-color-scheme="shiori"] {
+ --md-primary-fg-color: rgb(244, 67, 54);
+}
diff --git a/docs/screenshots/01-login.png b/docs/assets/screenshots/01-login.png
similarity index 100%
rename from docs/screenshots/01-login.png
rename to docs/assets/screenshots/01-login.png
diff --git a/docs/screenshots/02-home.png b/docs/assets/screenshots/02-home.png
similarity index 100%
rename from docs/screenshots/02-home.png
rename to docs/assets/screenshots/02-home.png
diff --git a/docs/screenshots/03-home-list.png b/docs/assets/screenshots/03-home-list.png
similarity index 100%
rename from docs/screenshots/03-home-list.png
rename to docs/assets/screenshots/03-home-list.png
diff --git a/docs/screenshots/04-options.png b/docs/assets/screenshots/04-options.png
similarity index 100%
rename from docs/screenshots/04-options.png
rename to docs/assets/screenshots/04-options.png
diff --git a/docs/screenshots/05-dark-login.png b/docs/assets/screenshots/05-dark-login.png
similarity index 100%
rename from docs/screenshots/05-dark-login.png
rename to docs/assets/screenshots/05-dark-login.png
diff --git a/docs/screenshots/06-dark-home.png b/docs/assets/screenshots/06-dark-home.png
similarity index 100%
rename from docs/screenshots/06-dark-home.png
rename to docs/assets/screenshots/06-dark-home.png
diff --git a/docs/screenshots/07-dark-home-list.png b/docs/assets/screenshots/07-dark-home-list.png
similarity index 100%
rename from docs/screenshots/07-dark-home-list.png
rename to docs/assets/screenshots/07-dark-home-list.png
diff --git a/docs/screenshots/08-dark-options.png b/docs/assets/screenshots/08-dark-options.png
similarity index 100%
rename from docs/screenshots/08-dark-options.png
rename to docs/assets/screenshots/08-dark-options.png
diff --git a/docs/screenshots/09-mobile-login.png b/docs/assets/screenshots/09-mobile-login.png
similarity index 100%
rename from docs/screenshots/09-mobile-login.png
rename to docs/assets/screenshots/09-mobile-login.png
diff --git a/docs/screenshots/10-mobile-home.png b/docs/assets/screenshots/10-mobile-home.png
similarity index 100%
rename from docs/screenshots/10-mobile-home.png
rename to docs/assets/screenshots/10-mobile-home.png
diff --git a/docs/screenshots/11-mobile-home-list.png b/docs/assets/screenshots/11-mobile-home-list.png
similarity index 100%
rename from docs/screenshots/11-mobile-home-list.png
rename to docs/assets/screenshots/11-mobile-home-list.png
diff --git a/docs/screenshots/12-mobile-options.png b/docs/assets/screenshots/12-mobile-options.png
similarity index 100%
rename from docs/screenshots/12-mobile-options.png
rename to docs/assets/screenshots/12-mobile-options.png
diff --git a/docs/screenshots/13-mobile-dark-login.png b/docs/assets/screenshots/13-mobile-dark-login.png
similarity index 100%
rename from docs/screenshots/13-mobile-dark-login.png
rename to docs/assets/screenshots/13-mobile-dark-login.png
diff --git a/docs/screenshots/14-mobile-dark-home.png b/docs/assets/screenshots/14-mobile-dark-home.png
similarity index 100%
rename from docs/screenshots/14-mobile-dark-home.png
rename to docs/assets/screenshots/14-mobile-dark-home.png
diff --git a/docs/screenshots/15-mobile-dark-home-list.png b/docs/assets/screenshots/15-mobile-dark-home-list.png
similarity index 100%
rename from docs/screenshots/15-mobile-dark-home-list.png
rename to docs/assets/screenshots/15-mobile-dark-home-list.png
diff --git a/docs/screenshots/16-mobile-dark-options.png b/docs/assets/screenshots/16-mobile-dark-options.png
similarity index 100%
rename from docs/screenshots/16-mobile-dark-options.png
rename to docs/assets/screenshots/16-mobile-dark-options.png
diff --git a/docs/readme/comparison.png b/docs/assets/screenshots/comparison.png
similarity index 100%
rename from docs/readme/comparison.png
rename to docs/assets/screenshots/comparison.png
diff --git a/docs/readme/cover.png b/docs/assets/screenshots/cover.png
similarity index 100%
rename from docs/readme/cover.png
rename to docs/assets/screenshots/cover.png
diff --git a/docs/Frequently-Asked-Question.md b/docs/faq.md
similarity index 100%
rename from docs/Frequently-Asked-Question.md
rename to docs/faq.md
diff --git a/docs/index.md b/docs/index.md
index 060793682..f69752e55 100644
--- a/docs/index.md
+++ b/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
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 000000000..e12a35607
--- /dev/null
+++ b/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