go-shiori · fmartingr · Aug 20, 2023 · Aug 20, 2023 · Aug 20, 2023 · Aug 26, 2023
diff --git a/.github/workflows/_mkdocs-check.yml b/.github/workflows/_mkdocs-check.yml
@@ -0,0 +1,18 @@
+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
@@ -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
@@ -16,8 +16,10 @@ jobs:
     uses: ./.github/workflows/_test.yml
   call-swagger-check:
     uses: ./.github/workflows/_swagger-check.yml
+  call-mkdocs-check:
+    uses: ./.github/workflows/_mkdocs-check.yml
   call-gorelease:
-    needs: [call-lint, call-test, call-swagger-check]
+    needs: [call-lint, call-test, call-swagger-check, call-mkdocs-check]
     uses: ./.github/workflows/_gorelease.yml
   call-buildx:
     needs: call-gorelease

diff --git a/.github/workflows/version_bump.yml b/.github/workflows/version_bump.yml
@@ -36,3 +36,7 @@ jobs:
   call-buildx:
     needs: call-gorelease
     uses: ./.github/workflows/_buildx.yml
+  call-mkdocs-publish:
+    needs: call-buildx
+    uses: ./.github/workflows/_mkdocs-publish.yml
+
diff --git a/.gitignore b/.gitignore
@@ -16,3 +16,7 @@ dist/
 
 # macOS trash files
 .DS_Store
+
+# Docs
+docs/.venv
+build/docs
diff --git a/Makefile b/Makefile
@@ -23,6 +23,10 @@ SHIORI_DEVELOPMENT ?= true
 SWAG_VERSION := v1.8.12
 SWAGGER_DOCS_PATH ?= ./docs/swagger
 
+# Docs
+DOCS_BUILD_PATH ?= ./build/docs
+MKDOCS_EXTRA_FLAGS ?=
+
 # Help documentatin à la https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
 .PHONY: help
 help:
@@ -81,3 +85,11 @@ build: clean
 coverage:
 	$(GO) test $(GO_TEST_FLAGS) -coverprofile=coverage.txt ./...
 	$(GO) tool cover -html=coverage.txt
+
+.PHONY: docs
+docs:
+	DOCS_BUILD_PATH=$(DOCS_BUILD_PATH) $(BASH) ./scripts/docs.sh
+
+.PHONY: docs-publish
+docs:
+	DOCS_ACTION=publish $(BASH) ./scripts/docs.sh
diff --git a/README.md b/README.md
@@ -7,20 +7,24 @@
 
 **Check out our latest [Announcements](https://github.com/go-shiori/shiori/discussions/categories/announcements)**
 
-Shiori is a simple bookmarks manager written in the Go language. Intended as a simple clone of [Pocket][pocket]. You can use it as a command line application or as a 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 the Go language. You can use it as a command line application or as a web application, distributed as a single binary, which means it can be installed and used easily.
+
+You can use it as a bookmark manager or as an alternative to [Pocket][pocket] or other read-later services due to it's archival and readability features.
 
 ![Screenshot][screenshot]
 
 ## Features
 
-- Basic bookmarks management i.e. add, edit, delete and search.
-- Import and export bookmarks from and to Netscape Bookmark file.
-- Import bookmarks from Pocket.
-- Simple and clean command line interface.
-- Simple and pretty web interface for those who don't want to use a command line app.
-- Portable, thanks to its single binary format.
-- Support for sqlite3, PostgreSQL and MySQL as its database.
-- Where possible, by default `shiori` will parse the readable content and create an offline archive of the webpage.
+- Basic **bookmarks management** i.e. add, edit, delete and search.
+- **Import and export** bookmarks from and to Netscape Bookmark file.
+- Import bookmarks from **Pocket**.
+- Simple and clean **command line interface**.
+- Simple and pretty **web interface** for those who don't want to use a command line app.
+- **Portable**, thanks to its single binary format.
+- Support for **sqlite3**, **PostgreSQL** and **MySQL** as its database.
+- Where possible and by default `shiori` will **parse the readable content**.
+- Optionally **create an offline archive of the webpage** using [warc](warc). (See [#353](https://github.com/go-shiori/shiori/issues/353))
+- Optionally **create an ebook** from the readable content in ePub using [go-epub][go-epub].
 - [BETA] [web extension][web-extension] support for Firefox and Chrome.
 
 ![Comparison of reader mode and archive mode][mode-comparison]
@@ -39,4 +43,5 @@ Shiori is distributed under the terms of the [MIT license][mit], which means you
 [screenshot]: https://raw.githubusercontent.com/go-shiori/shiori/master/docs/readme/cover.png
 [mode-comparison]: https://raw.githubusercontent.com/go-shiori/shiori/master/docs/readme/comparison.png
 [pocket]: https://getpocket.com/
+[warc]: https://github.com/go-shiori/warc
 [256]: https://github.com/go-shiori/shiori/issues/256
diff --git a/docs/Installation.md b/docs/Installation.md
diff --git a/docs/Configuration.md → docs/_old/Configuration.md b/docs/Configuration.md → docs/_old/Configuration.md
diff --git a/docs/Frequently-Asked-Question.md → docs/_old/Frequently-Asked-Question.md b/docs/Frequently-Asked-Question.md → docs/_old/Frequently-Asked-Question.md
diff --git a/docs/Screenshots.md → docs/_old/Screenshots.md b/docs/Screenshots.md → docs/_old/Screenshots.md
diff --git a/docs/Storage.md → docs/_old/Storage.md b/docs/Storage.md → docs/_old/Storage.md
diff --git a/docs/Usage.md → docs/_old/Usage.md b/docs/Usage.md → docs/_old/Usage.md
diff --git a/docs/assets/css/style.css 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/getting_started/installation.md b/docs/getting_started/installation.md
@@ -0,0 +1,101 @@
+# Installation
+
+There are several supported installation methods available:
+
+## Supported methods
+
+### Using Precompiled Binary
+
+Download the latest version of `shiori` from [the release page](https://github.com/go-shiori/shiori/releases/latest), then put it in your `PATH`.
+
+On Linux or MacOS, you can do it by adding this line to your profile file (either `$HOME/.bash_profile` or `$HOME/.profile`):
+
+``` sh
+export PATH=$PATH:/path/to/shiori
+```
+
+Note that this will not automatically update your path for the remainder of the session. To do this, you should run:
+
+``` sh
+source $HOME/.bash_profile
+or
+source $HOME/.profile
+```
+
+On Windows, you can simply set the `PATH` by using the advanced system settings.
+
+### Install building from source
+
+Shiori uses Go module so make sure you have version of `go >= 1.14.1` installed, then run:
+
+``` sh
+go install github.com/go-shiori/shiori@latest
+```
+
+> Ensure your `PATH` includes the `$GOPATH/bin` directory so your commands can be easily used:
+>
+> ``` sh
+> export PATH=$PATH:$(go env GOPATH)/bin
+> ```
+
+### Using Docker Image
+
+To use Docker image, you can pull the latest automated build from Docker Hub :
+
+```
+docker pull ghcr.io/go-shiori/shiori
+```
+
+> This docker image is based on the [Dockerfile.ci](../.github/workflows/docker/Dockerfile.ci)
+
+### Building docker image
+
+If you want to build the Docker image on your own, Shiori already has its [Dockerfile](https://github.com/go-shiori/shiori/blob/master/Dockerfile), so you can build the Docker image by running :
+
+```
+docker build -t shiori .
+```
+
+> This docker image is based on the root [Dockerfile](../Dockerfile)
+
+
+## Community provided
+
+There are other methods to have your own shiori instance running, but they are not officially supported by the Shiori team and have been provided by the community.
+
+Contributions are welcome!
+
+### Deploying with Fly.io
+
+**Contributed by:** [@jt-wang](https://github.com/jt-wang) (Thanks to [Oscar Carlsson's post](https://www.monotux.tech/posts/2022/09/more-flies-please/))
+
+You can also deploy direclty to [Fly.io](https://fly.io) using the docker image.
+
+- lauch a new Fly.io app, and create permanent storage
+
+``` shell
+cd directory-where-you-store-your-shiori-flyio-toml
+flyctl launch --no-deploy
+flyctl volumes create shiori_data --size 1
+```
+
+- Add the following sections to your fly.toml:
+
+``` ini
+[build]
+image = "ghcr.io/go-shiori/shiori:latest"
+
+[mounts]
+source="shiori_data" # change it if you use another volume name in step 1
+destination="/shiori"
+```
+
+- Deploy
+
+``` shell
+flyctl deploy
+```
+
+- Now the shiori app should run like expected. The default username is `shiori` and the default password is `gopher`, **ensure you change this credentials when you log in for the first time**.
+
+     You can run `flyctl open` to open your Shiori.
diff --git a/docs/images/logo.png b/docs/images/logo.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,15 +1,57 @@
-# 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
 
-## Resources
+Shiori is a simple bookmarks manager written in the Go language. You can use it as a command line application or as a web application, distributed as a single binary, which means it can be installed and used easily.
+
+You can use it as a bookmark manager or as an alternative to [Pocket][pocket] or other read-later services due to it's archival and readability features.
+
+![Screenshot][screenshot]
+
+## Features
+
+- Basic **bookmarks management** i.e. add, edit, delete and search.
+- **Import and export** bookmarks from and to Netscape Bookmark file.
+- Import bookmarks from **Pocket**.
+- Simple and clean **command line interface**.
+- Simple and pretty **web interface** for those who don't want to use a command line app.
+- **Portable**, thanks to its single binary format.
+- Support for **sqlite3**, **PostgreSQL** and **MySQL** as its database.
+- Where possible and by default `shiori` will **parse the readable content**.
+- Optionally **create an offline archive of the webpage** using [warc][warc]. (See [#353](https://github.com/go-shiori/shiori/issues/353))
+- Optionally **create an ebook** from the readable content in ePub using [go-epub][go-epub].
+- [BETA] [web extension][web-extension] support for Firefox and Chrome.
+
+![Comparison of reader mode and archive mode][mode-comparison]
+
+## License
+
+Shiori is distributed under the terms of the [MIT license][mit], which means you can use it and modify it however you want. However, if you make an enhancement for it, if possible, please send a pull request.
+
+[documentation]: https://github.com/go-shiori/shiori/blob/master/docs/index.md
+[mit]: https://choosealicense.com/licenses/mit/
+[web-extension]: https://github.com/go-shiori/shiori-web-ext
+[screenshot]: https://raw.githubusercontent.com/go-shiori/shiori/master/docs/readme/cover.png
+[mode-comparison]: https://raw.githubusercontent.com/go-shiori/shiori/master/docs/readme/comparison.png
+[go-epub]: https://github.com/bmaupin/go-epub
+[pocket]: https://getpocket.com/
+[warc]: https://github.com/go-shiori/warc
+[256]: https://github.com/go-shiori/shiori/issues/256
+
+
+<!-- ## Getting started
 
-- [API](./API.md) (Deprecated)
-- [APIv1](./APIv1.md) ([What is this?](https://github.com/go-shiori/shiori/issues/640))
-- [Contributing](./Contribute.md)
-- [Configuration](./Configuration.md)
-- [FAQ](./Frequently-Asked-Question.md)
 - [Installation](./Installation.md)
-- [Screenshots](./screenshots/)
+- [Configuration](./Configuration.md)
 - [Storage](./Storage.md)
-- [Usage](./Usage.md)
+- [Screenshots](./Screenshots.md)
+
+## Usage
+
+- [Command Line Interface](./CLI.md)
+- [Web Interface](./Web-Intarface.md)
+- [API (legacy)](./API.md) (**Deprecated!**, see [APIv1](./APIv1.md))
+- [APIv1](./APIv1.md) ([What is this?](https://github.com/go-shiori/shiori/issues/640))
+
+## Advanced
+
+- [Contributing](./Contribute.md) -->