diff --git a/README.md b/README.md index 284b2aa47..5972578e7 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ All documentation is available in the [docs folder][documentation]. If you think 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. +[getting started]: https://github.com/go-shiori/shiori/blob/master/docs/Getting-Started.md [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 diff --git a/docs/Usage.md b/docs/Usage.md index c4e965503..558316936 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -2,46 +2,15 @@ Before using `shiori`, make sure it has been installed on your system. By defaul -- [Running Docker Container](#running-docker-container) - [Using Command Line Interface](#using-command-line-interface) - [Search syntax](#search-syntax) -- [Using Web Interface](#using-web-interface) +- [How to use the Web Interface](#using-web-interface) + - [Adding bookmarks manually](#adding-bookmarks-manually) - [Improved import from Pocket](#improved-import-from-pocket) - [Import from Wallabag](#import-from-wallabag) -## Running Docker Container - -> If you are not using `shiori` from Docker image, you can skip this section. - -After building or pulling the image, you will be able to start a container from it. To preserve the data, you need to bind the directory for storing database, thumbnails and archive. In this example we're binding the data directory to our current working directory : - -``` -docker run -d --rm --name shiori -p 8080:8080 -v $(pwd):/shiori ghcr.io/go-shiori/shiori -``` - -The above command will : - -- Creates a new container from image `ghcr.io/go-shiori/shiori`. -- Set the container name to `shiori` (option `--name`). -- Bind the host current working directory to `/shiori` inside container (option `-v`). -- Expose port `8080` in container to port `8080` in host machine (option `-p`). -- Run the container in background (option `-d`). -- Automatically remove the container when it stopped (option `--rm`). - -After you've run the container in background, you can access console of the container: - -``` -docker exec -it shiori sh -``` - -Now you can use `shiori` like normal. If you've finished, you can stop and remove the container by running : - -``` -docker stop shiori -``` - ## Using Command Line Interface Shiori is composed by several subcommands. To see the documentation, run `shiori -h` : @@ -79,8 +48,7 @@ With the `print` command line interface, you can use `-s` flag to submit keyword You may also use `-t` flag to include tags and `-e` flag to exclude tags. - -## Using Web Interface +## How to use the Web Interface To access web interface run `shiori serve` or start Docker container following tutorial above. If you want to use a different port instead of 8080, you can simply run `shiori serve -p `. Once started you can access the web interface in `http://localhost:8080` or `http://localhost:` if you customized it. You will be greeted with login screen like this : @@ -105,6 +73,26 @@ When searching for bookmarks, you may use `tag:tagname` to include tags and `-ta - `Alt + Click` on the tag name to exclude it. +### Adding bookmarks manually + +- Within the web application, you can add a new bookmark by following the steps depicted in the screenshots below: + +![gs-01](./screenshots/17-gs-add-bookmark.png) +![gs-02](./screenshots/18-gs-add-bookmark.png) +![gs-03](./screenshots/19-gs-add-bookmark.png) + +This action will generate a new entry, as illustrated in the final screenshot. + +- Following this step, you should proceed to select the __Update Archive__ button in order to initiate the process of creating a local copy of the page. + +![gs-04](./screenshots/20-gs-add-bookmark.png) +![gs-05](./screenshots/21-gs-add-bookmark.png) + +- At this point, you will be able to observe your downloaded bookmark, which has been successfully stored locally. + +![gs-06](./screenshots/22-gs-add-bookmark.png) + + ## Improved import from Pocket Shiori offers a [Command Line Interface](https://github.com/go-shiori/shiori/blob/master/docs/Usage.md#using-command-line-interface) with the command `shiori pocket` to import Pocket entries but with this can only import them as links and not as complete entries. @@ -137,7 +125,6 @@ rm pocket2shiori.sh 'path_to_your/pocket_export.html' ## Import from Wallabag - 1. Export your entries from Wallabag as a json file 2. Install [jq](https://stedolan.github.io/jq/download/). You will need this installed before running the script. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..251973298 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,57 @@ +# Getting Started + +Before using `shiori`, make sure it has been installed on your system. By default, `shiori` will store its data in directory `$HOME/.local/share/shiori`. If you want to set the data directory to another location, you can set the environment variable `SHIORI_DIR` (`ENV_SHIORI_DIR` when you are before `1.5.0`) to your desired path. + + + +- [Running Docker Container](#running-docker-container) +- [How to use Shiori](#how-to-use-shiori) +- [Deleting/Stopping Shiori](#deletingstopping-shiori) + + + +## Running Docker Container + +> If you are not using `shiori` from Docker image, you can skip this section. + +After building or pulling the image, you will be able to start a container from it. To preserve the data, you need to bind the directory for storing database, thumbnails and archive. In this example we're binding the data directory to our current working directory : + +``` +docker run -d --rm --name shiori -p 8080:8080 -v $(pwd):/shiori ghcr.io/go-shiori/shiori +``` + +The above command will: + +- Creates a new container from image `ghcr.io/go-shiori/shiori`. +- Set the container name to `shiori` (option `--name`). +- Bind the host current working directory to `/shiori` inside container (option `-v`). +- Expose port `8080` in container to port `8080` in host machine (option `-p`). +- Run the container in background (option `-d`). +- Automatically remove the container when it stopped (option `--rm`). + +After you've run the container in background, you can access console of the container: + +``` +docker exec -it shiori sh +``` + +Now you can use `shiori` like normal. + +## How to use Shiori + +From this point you have the option to proceed to the [usage section](./Usage.md), where various modes of operation are elaborated upon: + +- [How to use the Web Interface](./Usage.md#using-web-interface) +- [Using the CLI](./Usage.md#using-command-line-interface) +- [Improved import from Pocket](./Usage.md#improved-import-from-pocket) +- [Import from Wallabag](./Usage.md#import-from-wallabag) + + +## Deleting/Stopping Shiori + +If you've finished, you can stop and remove the container by running : + +``` +docker stop shiori +``` + diff --git a/docs/index.md b/docs/index.md index 295d60024..ec3c976e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,7 @@ Shiori is a simple bookmarks manager written in Go language. Intended as a simpl ## Resources +- [Getting Started](./Getting-Started.md) - [API](./API.md) (Deprecated) - [APIv1](./APIv1.md) ([What is this?](https://github.com/go-shiori/shiori/issues/640)) - [Contributing](./Contribute.md) diff --git a/docs/screenshots/17-gs-add-bookmark.png b/docs/screenshots/17-gs-add-bookmark.png new file mode 100644 index 000000000..e48bfd55f Binary files /dev/null and b/docs/screenshots/17-gs-add-bookmark.png differ diff --git a/docs/screenshots/18-gs-add-bookmark.png b/docs/screenshots/18-gs-add-bookmark.png new file mode 100644 index 000000000..9c9d95669 Binary files /dev/null and b/docs/screenshots/18-gs-add-bookmark.png differ diff --git a/docs/screenshots/19-gs-add-bookmark.png b/docs/screenshots/19-gs-add-bookmark.png new file mode 100644 index 000000000..da27b03ca Binary files /dev/null and b/docs/screenshots/19-gs-add-bookmark.png differ diff --git a/docs/screenshots/20-gs-add-bookmark.png b/docs/screenshots/20-gs-add-bookmark.png new file mode 100644 index 000000000..dfd2051cd Binary files /dev/null and b/docs/screenshots/20-gs-add-bookmark.png differ diff --git a/docs/screenshots/21-gs-add-bookmark.png b/docs/screenshots/21-gs-add-bookmark.png new file mode 100644 index 000000000..47008e2fa Binary files /dev/null and b/docs/screenshots/21-gs-add-bookmark.png differ diff --git a/docs/screenshots/22-gs-add-bookmark.png b/docs/screenshots/22-gs-add-bookmark.png new file mode 100644 index 000000000..8257d41d4 Binary files /dev/null and b/docs/screenshots/22-gs-add-bookmark.png differ