[github/wallabag/wallabag.git] / docs / en / user / configuration.rst

Configuration
=============

Now you're logged in, it's time to configure your account as you want.

Click on ``Config`` menu. You have five tabs: ``Settings``, ``RSS``,
``User information``, ``Password`` and ``Tagging rules``.

Settings
--------

Theme
~~~~~

wallabag is customizable. You can choose your prefered theme here. You can also
create a new one, a chapter will be dedicated for this. The default theme is
``Material``, it's the theme used in the documentation screenshots.

Items per page
~~~~~~~~~~~~~~

You can change the number of articles displayed on each page.

Reading speed
~~~~~~~~~~~~~

wallabag calculates a reading time for each article. You can define here, thanks to this list, if you are
a fast or a slow reader. wallabag will recalculate the reading time for each article.

Language
~~~~~~~~

You can change the language of wallabag interface. You need to logout for this change
to take effect.

RSS
---

wallabag provides RSS feeds for each article status: unread, starred and archive.

Firstly, you need to create a personal token: click on ``Create your token``.
It's possible to change your token by clicking on ``Reset your token``.

Now you have three links, one for each status: add them into your favourite RSS reader.

You can also define how many articles you want in each RSS feed (default value: 50).

User information
----------------

You can change your name, your email address and enable ``Two factor authentication``.

If the wallabag instance has more than one enabled user, you can delete your account here. **Take care, we delete all your data**.

Two factor authentication
~~~~~~~~~~~~~~~~~~~~~~~~~

    Two-factor authentication (also known as 2FA) is a technology patented in 1984
    that provides identification of users by means of the combination of two different components.

https://en.wikipedia.org/wiki/Two-factor_authentication

If you enable 2FA, each time you want to login to wallabag, you'll receive
a code by email. You have to put this code on the following form.

.. image:: ../../img/user/2FA_form.png
    :alt: Two factor authentication
    :align: center

If you don't want to receive a code each time you want to login, you can check
the ``I'm on a trusted computer`` checkbox: wallabag will remember you for 15 days.

Password
--------

You can change your password here (8 characters minimum).

Tagging rules
-------------

If you want to automatically assign a tag to new articles, this part
of the configuration is for you.

What does « tagging rules » mean?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

They are rules used by wallabag to automatically tag new entries.
Each time a new entry is added, all the tagging rules will be used to add
the tags you configured, thus saving you the trouble to manually classify your entries.

How do I use them?
~~~~~~~~~~~~~~~~~~

Let assume you want to tag new entries as *« short reading »* when
the reading time is inferior to 3 minutes.
In that case, you should put « readingTime <= 3 » in the **Rule** field
and *« short reading »* in the **Tags** field.
Several tags can added simultaneously by separating them by a comma: *« short reading, must read »*.
Complex rules can be written by using predefined operators:
if *« readingTime >= 5 AND domainName = "github.com" »* then tag as *« long reading, github »*.

Which variables and operators can I use to write rules?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following variables and operators can be used to create tagging rules (be careful, for some values, you need to add quotes, for example ``language = "en"``):

===========  ==============================================  ========  ==========
Variable     Meaning                                         Operator  Meaning
-----------  ----------------------------------------------  --------  ----------
title        Title of the entry                              <=        Less than…
url          URL of the entry                                <         Strictly less than…
isArchived   Whether the entry is archived or not            =>        Greater than…
isStarred    Whether the entry is starred or not             >         Strictly greater than…
content      The entry's content                             =         Equal to…
language     The entry's language                            !=        Not equal to…
mimetype     The entry's mime-type                           OR        One rule or another
readingTime  The estimated entry's reading time, in minutes  AND       One rule and another
domainName   The domain name of the entry                    matches   Tests that a subject is matches a search (case-insensitive). Example: title matches "football"
===========  ==============================================  ========  ==========
Commit	Line	Data
	1	Configuration
	2	=============
	3
	4	Now you're logged in, it's time to configure your account as you want.
	5
	6	Click on ``Config`` menu. You have five tabs: ``Settings``, ``RSS``,
	7	``User information``, ``Password`` and ``Tagging rules``.
	8
	9	Settings
	10	--------
	11
	12	Theme
	13	~~~~~
	14
	15	wallabag is customizable. You can choose your prefered theme here. You can also
	16	create a new one, a chapter will be dedicated for this. The default theme is
	17	``Material``, it's the theme used in the documentation screenshots.
	18
	19	Items per page
	20	~~~~~~~~~~~~~~
	21
	22	You can change the number of articles displayed on each page.
	23
	24	Reading speed
	25	~~~~~~~~~~~~~
	26
	27	wallabag calculates a reading time for each article. You can define here, thanks to this list, if you are
	28	a fast or a slow reader. wallabag will recalculate the reading time for each article.
	29
	30	Language
	31	~~~~~~~~
	32
	33	You can change the language of wallabag interface. You need to logout for this change
	34	to take effect.
	35
	36	RSS
	37	---
	38
	39	wallabag provides RSS feeds for each article status: unread, starred and archive.
	40
	41	Firstly, you need to create a personal token: click on ``Create your token``.
	42	It's possible to change your token by clicking on ``Reset your token``.
	43
	44	Now you have three links, one for each status: add them into your favourite RSS reader.
	45
	46	You can also define how many articles you want in each RSS feed (default value: 50).
	47
	48	User information
	49	----------------
	50
	51	You can change your name, your email address and enable ``Two factor authentication``.
	52
	53	If the wallabag instance has more than one enabled user, you can delete your account here. Take care, we delete all your data.
	54
	55	Two factor authentication
	56	~~~~~~~~~~~~~~~~~~~~~~~~~
	57
	58	Two-factor authentication (also known as 2FA) is a technology patented in 1984
	59	that provides identification of users by means of the combination of two different components.
	60
	61	https://en.wikipedia.org/wiki/Two-factor_authentication
	62
	63	If you enable 2FA, each time you want to login to wallabag, you'll receive
	64	a code by email. You have to put this code on the following form.
	65
	66	.. image:: ../../img/user/2FA_form.png
	67	:alt: Two factor authentication
	68	:align: center
	69
	70	If you don't want to receive a code each time you want to login, you can check
	71	the ``I'm on a trusted computer`` checkbox: wallabag will remember you for 15 days.
	72
	73	Password
	74	--------
	75
	76	You can change your password here (8 characters minimum).
	77
	78	Tagging rules
	79	-------------
	80
	81	If you want to automatically assign a tag to new articles, this part
	82	of the configuration is for you.
	83
	84	What does « tagging rules » mean?
	85	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	86
	87	They are rules used by wallabag to automatically tag new entries.
	88	Each time a new entry is added, all the tagging rules will be used to add
	89	the tags you configured, thus saving you the trouble to manually classify your entries.
	90
	91	How do I use them?
	92	~~~~~~~~~~~~~~~~~~
	93
	94	Let assume you want to tag new entries as « short reading » when
	95	the reading time is inferior to 3 minutes.
	96	In that case, you should put « readingTime <= 3 » in the Rule field
	97	and « short reading » in the Tags field.
	98	Several tags can added simultaneously by separating them by a comma: « short reading, must read ».
	99	Complex rules can be written by using predefined operators:
	100	if « readingTime >= 5 AND domainName = "github.com" » then tag as « long reading, github ».
	101
	102	Which variables and operators can I use to write rules?
	103	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	104
	105	The following variables and operators can be used to create tagging rules (be careful, for some values, you need to add quotes, for example ``language = "en"``):
	106
	107	=========== ============================================== ======== ==========
	108	Variable Meaning Operator Meaning
	109	----------- ---------------------------------------------- -------- ----------
	110	title Title of the entry <= Less than…
	111	url URL of the entry < Strictly less than…
	112	isArchived Whether the entry is archived or not => Greater than…
	113	isStarred Whether the entry is starred or not > Strictly greater than…
	114	content The entry's content = Equal to…
	115	language The entry's language != Not equal to…
	116	mimetype The entry's mime-type OR One rule or another
	117	readingTime The estimated entry's reading time, in minutes AND One rule and another
	118	domainName The domain name of the entry matches Tests that a subject is matches a search (case-insensitive). Example: title matches "football"
	119	=========== ============================================== ======== ==========