fmartingr
/
shiori
mirror of https://github.com/fmartingr/shiori.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: moved wiki inside docs folder

This commit is contained in:
Felipe M 2022-01-26 22:50:16 +01:00
parent 5c95462a67
commit a0c56686a9
Signed by: fmartingr
GPG Key ID: 716BC147715E716F
8 changed files with 946 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@ -1,13 +1,9 @@
# Shiori
[![CI](https://github.com/go-shiori/shiori/workflows/CI/badge.svg)](https://github.com/go-shiori/shiori/actions?query=workflow%3ACI)
[![Go Report Card](https://goreportcard.com/badge/github.com/go-shiori/shiori)](https://goreportcard.com/report/github.com/go-shiori/shiori)
[![Docker Image](https://img.shields.io/static/v1?label=image&message=Docker&color=1488C6&logo=docker)](https://hub.docker.com/r/radhifadlillah/shiori)
[![Deploy Heroku](https://img.shields.io/static/v1?label=deploy&message=Heroku&color=430098&logo=heroku)](https://heroku.com/deploy)
[![CI](https://github.com/fmartingr/shiori/workflows/CI/badge.svg)](https://github.com/fmartingr/shiori/actions?query=workflow%3ACI)
[![Go Report Card](https://goreportcard.com/badge/github.com/fmartingr/shiori)](https://goreportcard.com/report/github.com/fmartingr/shiori)
**This project is now maintained by Dean Jackson (@deanishe).** The awesome original author, @RadhiFadlillah, unfortunately no longer has the time (see [#256][256]), and I am honoured to take over stewardship of such a fantastic application.
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/read-later manager written in the Go language intended as a simple clone of [Pocket][pocket]/[instapapter][instapaper]. 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.
![Screenshot][screenshot]
@ -15,7 +11,7 @@ Shiori is a simple bookmarks manager written in the Go language. Intended as a s
- Basic bookmarks management i.e. add, edit, delete and search.
- Import and export bookmarks from and to Netscape Bookmark file.
- Import bookmarks from Pocket.
- Import 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.
@ -23,20 +19,18 @@ Shiori is a simple bookmarks manager written in the Go language. Intended as a s
- Where possible, by default `shiori` will parse the readable content and create an offline archive of the webpage.
- [BETA] [web extension][web-extension] support for Firefox and Chrome.
![Comparison of reader mode and archive mode][mode-comparison]
## Documentation
All documentation is available in the [wiki][wiki]. If you think there is incomplete or incorrect information, feel free to edit it.
All documentation is available under the [docs][docs] folder. If you think there is incomplete or incorrect information, feel free to submit a patch.
## 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.
[wiki]: https://github.com/go-shiori/shiori/wiki
[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
[pocket]: https://getpocket.com/
[256]: https://github.com/go-shiori/shiori/issues/256
[instapaper]: https://instapaper.com
[docs]: ./docs

47
docs/Installation.md Normal file
View File

@ -0,0 +1,47 @@
There are several installation methods available :
- [Using precompiled binary](#using-precompiled-binary)
- [Building from source](#building-from-source)
- [Using Docker image](#using-docker-image)
## Using Precompiled Binary
Download the latest version of `shiori` from [the release page](https://github.com/RadhiFadlillah/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`):
```
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:
```
source $HOME/.bash_profile
or
source $HOME/.profile
```
On Windows, you can simply set the `PATH` by using the advanced system settings.
## Building From Source
Shiori uses Go module so make sure you have version of `go >= 1.14.1` installed, then run:
```
go get -u -v github.com/go-shiori/shiori
```
## Using Docker Image
To use Docker image, you can pull the latest automated build from Docker Hub :
```
docker pull radhifadlillah/shiori
```
If you want to build the Docker image on your own, Shiori already has its [Dockerfile](https://github.com/RadhiFadlillah/shiori/blob/master/Dockerfile), so you can build the Docker image by running :
```
docker build -t shiori .
```

288
docs/api.md Normal file
View File

@ -0,0 +1,288 @@
This is a brief explanation of Shiori's API. For more examples you can import this [collection](https://github.com/go-shiori/shiori/blob/master/docs/postman/shiori.postman_collection.json) in Postman.
#### Table of contents
* [Auth](#Auth)
* [Log in](#Log-in)
* [Log out](#Log-out)
* [Bookmarks](#Bookmarks)
* [Get Bookmarks](#Get-Bookmarks)
* [Add Bookmark](#Add-bookmark)
* [Edit Bookmark](#Edit-bookmark)
* [Delete Bookmark](#Delete-bookmark)
* [Tags](#Tags)
* [Get Tags](#Get-tags)
* [Rename Tag](#Rename-tag)
* [Accounts](#Accounts)
* [List Accounts](#List-accounts)
* [Create account](#Create-account)
* [Edit Account](#Edit-account)
* [Delete Accounts](#Delete-accounts)
# Auth
## Log in
Most actions require a session id. For that, you'll need to log in using your username and password.
|Request info|Value|
|-|-|
|Endpoint|`/api/login`|
|Method|`POST`|
Body:
```json
{
"username": "shiori",
"password": "gopher",
"remember": 1,
"owner": true
}
```
It will return your session ID in a JSON:
```json
{
"session": "YOUR_SESSION_ID",
"account": {
"id": 1,
"username": "shiori",
"owner": true
}
}
```
## Log out
Log out of a session ID.
|Request info|Value|
|-|-|
|Endpoint|`/api/logout`|
|Method|`POST`|
|`X-Session-Id` Header|`sessionId`|
# Bookmarks
## Get bookmarks
Gets the last 30 bookmarks (last page).
|Request info|Value|
|-|-|
|Endpoint|`/api/bookmarks`|
|Method|`GET`|
|`X-Session-Id` Header|`sessionId`|
Returns:
```json
{
"bookmarks": [
{
"id": 825,
"url": "https://interesting_cool_article.com",
"title": "Cool Interesting Article",
"excerpt": "An interesting and cool article indeed!",
"author": "",
"public": 0,
"modified": "2020-12-06 00:00:00",
"imageURL": "",
"hasContent": true,
"hasArchive": true,
"tags": [
{
"id": 7,
"name": "TAG"
}
],
"createArchive": false
},
],
"maxPage": 19,
"page": 1
}
```
## Add bookmark
Add a bookmark. For some reason, Shiori ignores the provided title and excerpt, and instead fetches them automatically. Note the tag format, a regular JSON list will result in an error.
|Request info|Value|
|-|-|
|Endpoint|`/api/bookmarks`|
|Method|`POST`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
{
"url": "https://interesting_cool_article.com",
"createArchive": true,
"public": 1,
"tags": [{"name": "Interesting"}, {"name": "Cool"}],
"title": "Cool Interesting Article",
"excerpt": "An interesting and cool article indeed!"
}
```
Returns:
```json
{
"id": 827,
"url": "https://interesting_cool_article.com",
"title": "TITLE",
"excerpt": "EXCERPT",
"author": "AUTHOR",
"public": 1,
"modified": "DATE",
"html": "HTML",
"imageURL": "/bookmark/827/thumb",
"hasContent": false,
"hasArchive": true,
"tags": [
{
"name": "Interesting"
},
{
"name": "Cool"
}
],
"createArchive": true
}
```
## Edit bookmark
Modifies a bookmark, by ID.
|Request info|Value|
|-|-|
|Endpoint|`/api/bookmarks`|
|Method|`PUT`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
{
"id": 3,
"url": "https://interesting_cool_article.com",
"title": "Cool Interesting Article",
"excerpt": "An interesting and cool article indeed!",
"author": "AUTHOR",
"public": 1,
"modified": "2019-09-22 00:00:00",
"imageURL": "/bookmark/3/thumb",
"hasContent": false,
"hasArchive": false,
"tags": [],
"createArchive": false
}
```
After providing the ID, provide the modified fields. The syntax is the same as [adding](#Add-a-bookmark).
## Delete bookmark
Deletes a list of bookmarks, by their IDs.
|Request info|Value|
|-|-|
|Endpoint|`/api/bookmarks`|
|Method|`DEL`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
[1, 2, 3]
```
# Tags
## Get tags
Gets the list of tags, their IDs and the number of entries that have those tags.
|Request info|Value|
|-|-|
|Endpoint|`/api/tags`|
|Method|`GET`|
|`X-Session-Id` Header|`sessionId`|
Returns:
```json
[
{
"id": 1,
"name": "Cool",
"nBookmarks": 1
},
{
"id": 2,
"name": "Interesting",
"nBookmarks": 1
}
```
## Rename tag
Renames a tag, provided its ID.
|Request info|Value|
|-|-|
|Endpoint|`/api/tag`|
|Method|`PUT`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
{
"id": 1,
"name": "TAG_NEW_NAME"
}
```
# Accounts
## List accounts
Gets the list of all user accounts, their IDs, and whether or not they are owners.
|Request info|Value|
|-|-|
|Endpoint|`/api/accounts`|
|Method|`GET`|
|`X-Session-Id` Header|`sessionId`|
Returns:
```json
[
{
"id": 1,
"username": "shiori",
"owner": true
}
]
```
## Create account
Creates a new user.
|Request info|Value|
|-|-|
|Endpoint|`/api/accounts`|
|Method|`POST`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
{
"username": "shiori2",
"password": "gopher",
"owner": false
}
```
## Edit account
Changes an account's password or owner status.
|Request info|Value|
|-|-|
|Endpoint|`/api/accounts`|
|Method|`PUT`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
{
"username": "shiori",
"oldPassword": "gopher",
"newPassword": "gopher",
"owner": true
}
```
## Delete accounts
Deletes a list of users.
|Request info|Value|
|-|-|
|Endpoint|`/api/accounts`|
|Method|`DEL`|
|`X-Session-Id` Header|`sessionId`|
Body:
```json
["shiori", "shiori2"]
```

52
docs/configuration.md Normal file
View File

@ -0,0 +1,52 @@
Content
---
- [Data directory](#data-directory)
- [Database](#database)
Data Directory
---
Shiori is designed to work out of the box, but you can change where it stores your bookmarks if you need to.
By default, Shiori saves your bookmarks in one of the following directories:
| Platform | Directory |
|----------|--------------------------------------------------------------|
| Linux | `${XDG_DATA_HOME}/shiori` (default: `~/.local/share/shiori`) |
| macOS | `~/Library/Application Support/shiori` |
| Windows | `%LOCALAPPDATA%/shiori` |
If you pass the flag `--portable` to Shiori, your data will be stored in the `shiori-data` subdirectory alongside the shiori executable.
To specify a custom path, set the `SHIORI_DIR` environment variable.
Database
---
Shiori uses an SQLite3 database stored in the above data directory by default. If you prefer, you can also use MySQL or PostgreSQL database by setting it in environment variables.
### MySQL
| Variable | Description |
|------------------------|-----------------------------------------------------|
| `SHIORI_DBMS` | Must be set to `mysql` |
| `SHIORI_MYSQL_USER` | Name of MySQL user |
| `SHIORI_MYSQL_PASS` | Password for the above user |
| `SHIORI_MYSQL_NAME` | Name of database to use |
| `SHIORI_MYSQL_ADDRESS` | Address of MySQL server, e.g. `tcp(127.0.0.1:3306)` or `unix(/tmp/mysqld.sock)` |
### PostgreSQL
| Variable | Description |
|---------------------|--------------------------------------------|
| `SHIORI_DBMS` | Must be set to `postgresql` |
| `SHIORI_PG_USER` | Name of PostgreSQL user |
| `SHIORI_PG_PASS` | Password for the above user |
| `SHIORI_PG_NAME` | Name of database to use |
| `SHIORI_PG_HOST` | Address of PostgreSQL server |
| `SHIORI_PG_PORT` | Port number used by PostgreSQL server |
[wiki]: https://github.com/go-shiori/shiori/wiki

256
docs/faq.md Normal file
View File

@ -0,0 +1,256 @@
Contents
---
### [General](#general-1)
- [What is this project ?](#what-is-this-project-)
- [How does it compare to other bookmarks manager ?](#how-does-it-compare-to-other-bookmarks-manager-)
- [What are the system requirements ?](#what-are-the-system-requirements-)
- [What is the status for this app ?](#what-is-the-status-for-this-app-)
- [Is this app actively maintained ?](#is-this-app-actively-maintained-)
- [How to make a contribution ?](#how-to-make-a-contribution-)
- [How to make a donation ?](#how-to-make-a-donation-)
### [Common issues](#common-issues-1)
- [Where is MacOS prebuilt binary ?](#where-is-macos-prebuilt-binary-)
- [What is the default account to login at the first time ?](#what-is-the-default-account-to-login-at-the-first-time-)
- [Why my old accounts can't do anything after upgrading Shiori to v1.5.0 ?](#why-my-old-accounts-cant-do-anything-after-upgrading-shiori-to-v150-)
### [Advanced](#advanced-1)
- [How to run `shiori` on start up ?](#how-to-run-shiori-on-start-up-)
- [How to cross compile from Linux to Windows ?](#how-to-cross-compile-from-linux-to-windows-)
General
---
### What is this project ?
Shiori is a bookmarks manager that built with Go. I've got the idea to make this after reading a comment on HN back in [April 2017](https://news.ycombinator.com/item?id=14203383) :
```
... for me the dream bookmark manager would be something really simple
with two commands like:
$ bookmark add http://...
That will:
a. Download a static copy of the webpage in a single HTML file, with a
PDF exported copy, that also take care of removing ads and
unrelated content from the stored content.
b. Run something like http://smmry.com/ to create a summary of the page
in few sentences and store it.
c. Use NLP techniques to extract the principle keywords and use them
as tags
And another command like:
$ bookmark search "..."
That will:
d. Not use regexp or complicated search pattern, but instead;
e. Search titles, tags, page content smartly and interactively, and;
f. Sort/filter results smartly by relevance, number of matches,
frequency, or anything else useful
g. Storing everything in a git repository or simple file structure
for easy synchronization, bonus point for browsers integrations.
```
I do like using bookmarks and those idea sounds useful to me. More importantly, it seems possible enough to do. Not too hard that it's impossible for me, but not too easy that it doesn't teach me anything. Looking back now, the only thing that I (kind of) managed to do is a, b, d and e. But it's enough for me, so it's fine I guess :laughing:.
### How does it compare to other bookmarks manager ?
To be honest I don't know. The only bookmarks manager that I've used is Pocket and the one that bundled in web browser. I do like Pocket though. However, since bookmarks is kind of sensitive data, I prefer it stays offline or in my own server.
### What are the system requirements ?
It runs in the lowest tier of Digital Ocean VPS, so I guess it should be able to run anywhere.
### What is the status for this app ?
It's stable enough to use and the database shouldn't be changed anymore. However, my bookmarks at most is only several hundred entries, therefore I haven't test whether it able to process or imports huge amount of bookmarks. If you would, please do try it.
### Is this app actively maintained ?
Yes, however the development pace might be really slow, especially when my day job is in busy season.
### How to make a contribution ?
Just like other open source projects, you can make a contribution by submitting issues or pull requests.
### How to make a donation ?
If you like this project, you can donate to me either via [PayPal](https://www.paypal.me/RadhiFadlillah) or [Ko-Fi](https://ko-fi.com/radhifadlillah).
Common Issues
---
### Where is MacOS prebuilt binary ?
Since `shiori` is using SQLite, it needs to be compiled using `cgo`. Therefore, to cross compile it from Linux, we need a cross compiler for `darwin`. This is hard because we need to download XCode and Apple's GCC compiler. There are multiple guides on how to do this, however I haven't got the time to do it. For more detail, you can check this [issue](https://github.com/mozilla/masche/issues/33) which trying to do it.
### What is the default account to login at the first time ?
The default account is `shiori` with password `gopher`.
It is removed once another 'owner' account is created.
### Why my old accounts can't do anything after upgrading Shiori to v1.5.0 ?
This issue happened because in Shiori v1.0.0 there are no account level, which means everyone is treated as owner. However, in Shiori v1.5.0 there are two account levels i.e. owner and visitor. The level difference is stored in [database](https://github.com/go-shiori/shiori/blob/master/internal/database/sqlite.go#L42-L48) as boolean value in column `owner` with default value false (which means by default all account is visitor, unless specified otherwise).
Because in v1.5.0 by default all account is visitor, when updating from v1.0 to v1.5 all of the old accounts by default will be marked as visitor. Fortunately, when there are no owner registered in database, we can login as owner using default account.
So, as workaround for this issue, you should :
- Login as default account.
- Go to options page.
- Remove your old accounts.
- Recreate them, but now as owner.
For more details see [#148](https://github.com/go-shiori/shiori/issues/148).
Advanced
---
### How to run `shiori` on start up ?
There are several methods to run `shiori` on start up, however the most recommended is running it as a service.
1. Create a service unit for `systemd` at `/etc/systemd/system/shiori.service`.
* Shiori is run via `docker` :
```ini
[Unit]
Description=Shiori container
After=docker.service
[Service]
Restart=always
ExecStartPre=-/usr/bin/docker rm shiori-1
ExecStart=/usr/bin/docker run \
--rm \
--name shiori-1 \
-p 8080:8080 \
-v /srv/machines/shiori:/srv/shiori \
radhifadlillah/shiori
ExecStop=/usr/bin/docker stop -t 2 shiori-1
[Install]
WantedBy=multi-user.target
```
* Shiori without `docker`. Set absolute path to `shiori` binary. `--portable` sets the data directory to be alongside the executable.
```ini
[Unit]
Description=Shiori service
[Service]
ExecStart=/home/user/go/bin/shiori serve --portable
Restart=always
[Install]
WantedBy=multi-user.target
```
* Shiori without `docker` and without `--portable` but secure.
```ini
[Unit]
Description=shiori service
Requires=network-online.target
After=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/shiori serve
Restart=always
User=shiori
Group=shiori
Environment="SHIORI_DIR=/var/lib/shiori"
DynamicUser=true
PrivateUsers=true
ProtectHome=true
ProtectKernelLogs=true
RestrictAddressFamilies=AF_INET AF_INET6
StateDirectory=shiori
SystemCallErrorNumber=EPERM
SystemCallFilter=@system-service
SystemCallFilter=~@chown
SystemCallFilter=~@keyring
SystemCallFilter=~@memlock
SystemCallFilter=~@setuid
DeviceAllow=
CapabilityBoundingSet=
LockPersonality=true
MemoryDenyWriteExecute=true
NoNewPrivileges=true
PrivateDevices=true
PrivateTmp=true
ProtectControlGroups=true
ProtectKernelTunables=true
ProtectSystem=full
ProtectClock=true
ProtectKernelModules=true
ProtectProc=noaccess
ProtectHostname=true
ProcSubset=pid
RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true
SystemCallArchitectures=native
SystemCallFilter=~@clock
SystemCallFilter=~@debug
SystemCallFilter=~@module
SystemCallFilter=~@mount
SystemCallFilter=~@raw-io
SystemCallFilter=~@reboot
SystemCallFilter=~@privileged
SystemCallFilter=~@resources
SystemCallFilter=~@cpu-emulation
SystemCallFilter=~@obsolete
UMask=0077
[Install]
WantedBy=multi-user.target
```
2. Set up data directory if Shiori with `docker`
This assumes, that the Shiori container has a runtime directory to store their
database, which is at `/srv/machines/shiori`. If you want to modify that,
make sure, to fix your `shiori.service` as well.
```sh
install -d /srv/machines/shiori
```
3. Enable and start the service
```sh
systemctl enable --now shiori
```
### How to cross compile from Linux to Windows ?
First we need to install `mingw-w64` for cross compiling. Assuming you are using Ubuntu the command will look like this :
```
$ sudo apt-get install gcc-mingw-w64
```
Now we can build for Windows 64-bit and 32-bit. To do so, `cd` to the `shiori` directory then run following commands :
```sh
# For Windows 64-bit
GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc CGO_ENABLED=1 go build -o shiori-windows-amd64.exe
# For Windows 32-bit
GOOS=windows GOARCH=386 CC=i686-w64-mingw32-gcc CGO_ENABLED=1 go build -o shiori-windows-386.exe
```

8
docs/index.md Normal file
View File

@ -0,0 +1,8 @@
## Docs
- [API](./api.md)
- [Configuration](./configuration.md)
- [FAQ](./faq.md)
- [Installation](./installation.md)
- [Screenshots](./screenshots.md)
- [Usage](./usage.md)

139
docs/screenshots.md Normal file
View File

@ -0,0 +1,139 @@
Desktop
---
<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="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/01-login.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/01-login.png">
</a>
</td>
<td width="50%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/05-dark-login.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/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="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/02-home.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/02-home.png">
</a>
</td>
<td width="50%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/06-dark-home.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/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="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/03-home-list.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/03-home-list.png">
</a>
</td>
<td width="50%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/07-dark-home-list.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/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="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/04-options.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/04-options.png">
</a>
</td>
<td width="50%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/08-dark-options.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/08-dark-options.png">
</a>
</td>
</tr>
</table>
Mobile
------
<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="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/09-mobile-login.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/09-mobile-login.png">
</a>
</td>
<td width="25%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/13-mobile-dark-login.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/13-mobile-dark-login.png">
</a>
</td>
<td width="25%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/10-mobile-home.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/10-mobile-home.png">
</a>
</td>
<td width="25%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/14-mobile-dark-home.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/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="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/11-mobile-home-list.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/11-mobile-home-list.png">
</a>
</td>
<td width="25%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/15-mobile-dark-home-list.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/15-mobile-dark-home-list.png">
</a>
</td>
<td width="25%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/12-mobile-options.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/12-mobile-options.png">
</a>
</td>
<td width="25%">
<a href="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/16-mobile-dark-options.png">
<img src="https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/16-mobile-dark-options.png">
</a>
</td>
</tr>
</table>

149
docs/usage.md Normal file
View File

@ -0,0 +1,149 @@
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)
- [Using Command Line Interface](#using-command-line-interface)
- [Using Web Interface](#using-web-interface)
- [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):/srv/shiori radhifadlillah/shiori
```
The above command will :
- Creates a new container from image `radhifadlillah/shiori`.
- Set the container name to `shiori` (option `--name`).
- Bind the host current working directory to `/srv/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` :
```
Simple command-line bookmark manager built with Go
Usage:
shiori [command]
Available Commands:
add Bookmark the specified URL
check Find bookmarked sites that no longer exists on the internet
delete Delete the saved bookmarks
export Export bookmarks into HTML file in Netscape Bookmark format
help Help about any command
import Import bookmarks from HTML file in Netscape Bookmark format
open Open the saved bookmarks
pocket Import bookmarks from Pocket's exported HTML file
print Print the saved bookmarks
serve Serve web interface for managing bookmarks
update Update the saved bookmarks
Flags:
-h, --help help for shiori
--portable run shiori in portable mode
Use "shiori [command] --help" for more information about a command.
```
### Search syntax
With the `print` command line interface, you can use `-s` flag to submit keywords that will be searched either in url, title, excerpts or cached content.
You may also use `-t` flag to include tags and `-e` flag to exclude tags.
## Using 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 <portnumber>`. Once started you can access the web interface in `http://localhost:8080` or `http://localhost:<portnumber>` if you customized it. You will be greeted with login screen like this :
![Login screen](https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/01-login.png)
Since this is our first time, we don't have any account registered yet. With that said, we can use the default user to access web interface :
```
username: shiori
password: gopher
```
Once login succeed you will be able to use the web interface. To add the new account, open the settings page and add accounts as needed :
![Options page](https://raw.githubusercontent.com/go-shiori/shiori/master/docs/screenshots/04-options.png)
The first new account you add will become the owner and it will deactivate the "shiori:gopher" default user automatically.
When searching for bookmarks, you may use `tag:tagname` to include tags and `-tag:tagname` to exclude tags in the search bar. You can also use tags dialog to do this :
- `Click` on the tag name to include it;
- `Alt + Click` on the tag name to exclude it.
## Improved import from Pocket
Shiori offers a [Command Line Interface](https://github.com/go-shiori/shiori/wiki/Usage#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.
To import your bookmarks from [Pocket](https://getpocket.com/) with the text and images follow these simple steps (based on [Issue 252](https://github.com/go-shiori/shiori/issues/252)):
1. Export your entries from Pocket by visiting https://getpocket.com/export
2. Download [this shell script](https://gist.githubusercontent.com/dchakro/fa43b0e89f884826d3bd60f51e48b078/raw/pocket2shiori.sh). [*You need to download this in your docker container or on the device that you are hosting shiori*]. Name it for instance `pocket2shiori.sh`.
> Tip: checkout the wiki for [opening a console in the docker container](https://github.com/go-shiori/shiori/wiki/Usage#running-docker-container).
3. Execute the shell script.
Here are the commands you need to run:
```sh
wget 'https://gist.githubusercontent.com/dchakro/fa43b0e89f884826d3bd60f51e48b078/raw/pocket2shiori.sh'
chmod +x pocket2shiori.sh
pocket2shiori.sh 'path_to_your/pocket_export.html'
```
> Tip: If you’re using shiori's docker container, ensure that the exported HTML from pocket is accessible inside the docker container.
You should now see `shiori` importing your Pocket entries properly with the text and images.
This is optional, but once the import is complete you can clean up by running:
```sh
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.
3. Download the shell script
[here](https://gist.githubusercontent.com/Aerex/01499c66f6b36a5d997f97ca1b0ab5b1/raw/bf793515540278fc675c7769be74a77ca8a41e62/wallabag2shiori). Similar to the `pocket2shiori.sh` script if you are shiori is in a docker container you will next to run this script
inside the container.
4. Execute the script. Here are the commands that you can run.
```sh
curl -sSOL
https://gist.githubusercontent.com/Aerex/01499c66f6b36a5d997f97ca1b0ab5b1/raw/bf793515540278fc675c7769be74a77ca8a41e62/wallabag2shiori'
chmod +x wallabag2shiori
./wallbag2shiori 'path/to/to/wallabag_export_json_file'
```