self-hosted/joplin
1
0
Fork 0
mirror of https://github.com/laurent22/joplin.git synced 2024-12-27 10:32:58 +02:00
Code Issues Releases Activity

Doc: Documentation update (released version v1.5.14) (#4306)

Browse Source
This commit is contained in:
Daeraxa 2021-01-20 11:59:03 +00:00 committed by GitHub
parent f37d37e613
commit 197e43d78a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 262 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
README.md
View File

@ -98,7 +98,7 @@ The Web Clipper is a browser extension that allows you to save web pages and scr
- [Joplin API Overview](https://github.com/laurent22/joplin/blob/dev/readme/api/overview.md)
- [Plugin development](https://github.com/laurent22/joplin/blob/dev/readme/api/get_started/plugins.md)
- [Plugin tutorial](https://github.com/laurent22/joplin/blob/dev/readme/api/tutorials/toc_plugin.md)
- Joplin API - References
@ -135,22 +135,29 @@ The Web Clipper is a browser extension that allows you to save web pages and scr
- Desktop, mobile and terminal applications.
- [Web Clipper](https://github.com/laurent22/joplin/blob/dev/readme/clipper.md) for Firefox and Chrome.
- End To End Encryption (E2EE)
- Note history (revisions)
- End To End Encryption (E2EE).
- Note history (revisions).
- Synchronisation with various services, including Nextcloud, Dropbox, WebDAV and OneDrive.
- Offline first, so the entire data is always available on the device even without an internet connection.
- Import Enex files (Evernote export format) and Markdown files.
- Export JEX files (Joplin Export format) and raw files.
- Support notes, to-dos, tags and notebooks.
- Goto Anything feature.
- Sort notes by multiple criteria - title, updated time, etc.
- Support for alarms (notifications) in mobile and desktop applications.
- Offline first, so the entire data is always available on the device even without an internet connection.
- Markdown notes, which are rendered with images and formatting in the desktop and mobile applications. Support for extra features such as math notation and checkboxes.
- File attachment support - images are displayed, and other files are linked and can be opened in the relevant application.
- Choice of both Markdown and Rich Text (WYSIWYG) editors.
- File attachment support - images are displayed, other files are linked and can be opened in the relevant application.
- Inline display of PDF, video and audio files.
- Goto Anything feature.
- Search functionality.
- Geo-location support.
- Supports multiple languages
- Supports multiple languages.
- External editor support - open notes in your favorite external editor with one click in Joplin.
- Extensible functionality through plugin and data APIs.
- Template support with data variables for auto creation of time & dates.
- Custom CSS support for customisation of both the rendered markdown and overall user interface.
- Customisable layout allows toggling, movement and sizing of various elements.
- Keyboard shortcuts are editable and allow binding of most Joplin commands with export/import functionality.
# Importing
@ -160,7 +167,7 @@ Joplin was designed as a replacement for Evernote and so can import complete Eve
- Recognition data - Evernote images, in particular scanned (or photographed) documents have [recognition data](https://en.wikipedia.org/wiki/Optical_character_recognition) associated with them. It is the text that Evernote has been able to recognise in the document. This data is not preserved when the note are imported into Joplin. However, should it become supported in the search tool or other parts of Joplin, it should be possible to regenerate this recognition data since the actual image would still be available.
- Colour, font sizes and faces - Evernote text is stored as HTML and this is converted to Markdown during the import process. For notes that are mostly plain text or with basic formatting (bold, italic, bullet points, links, etc.) this is a lossless conversion, and the note, once rendered back to HTML should be very similar. Tables are also imported and converted to Markdown tables. For very complex notes, some formatting data might be lost - in particular colours, font sizes and font faces will not be imported. The text itself however is always imported in full regardless of formatting.
- Colour, font sizes and faces - Evernote text is stored as HTML and this is converted to Markdown during the import process. For notes that are mostly plain text or with basic formatting (bold, italic, bullet points, links, etc.) this is a lossless conversion, and the note, once rendered back to HTML should be very similar. Tables are also imported and converted to Markdown tables. For very complex notes, some formatting data might be lost - in particular colours, font sizes and font faces will not be imported. The text itself however is always imported in full regardless of formatting. If it is essential that this extra data is preserved then Joplin also allows import of ENEX files as HTML.
To import Evernote data, first export your Evernote notebooks to ENEX files as described [here](https://help.evernote.com/hc/en-us/articles/209005557-How-to-back-up-export-and-restore-import-notes-and-notebooks). Then follow these steps:
@ -172,7 +179,9 @@ In the **terminal application**, in [command-line mode](https://github.com/laure
Joplin can import notes from plain Markdown file. You can either import a complete directory of Markdown files or individual files.
In the **desktop application**, open File > Import > MD and select your Markdown file or directory.
In the **desktop application**:
* **File import**: Go to File > Import > MD - Markdown (file) and select the Markdown file. This file will then be imported to the currently selected Notebook.
* **Directory import**: Go to File > Import > MD - Markdown (directory) and select the top level of the directory that is being imported. Directory (folder) structure will be preserved in the Notebook > Subnotebook > Note structure within Joplin.
In the **terminal application**, in [command-line mode](https://github.com/laurent22/joplin/blob/dev/readme/terminal.md#command-line-mode), type `import --format md /path/to/file.md` or `import --format md /path/to/directory/`.
@ -188,18 +197,23 @@ In general the way to import notes from any application into Joplin is to conver
# Exporting
Joplin can export to the JEX format (Joplin Export file), which is a tar file that can contain multiple notes, notebooks, etc. This is a lossless format in that all the notes, but also metadata such as geo-location, updated time, tags, etc. are preserved. This format is convenient for backup purposes and can be re-imported into Joplin. A "raw" format is also available. This is the same as the JEX format except that the data is saved to a directory and each item represented by a single file.
Joplin is also capable of exporting to a number of other formats including HTML and PDF which can be done for single notes, notebooks or everything.
# Synchronisation
One of the goals of Joplin was to avoid being tied to any particular company or service, whether it is Evernote, Google or Microsoft. As such the synchronisation is designed without any hard dependency to any particular service. Most of the synchronisation process is done at an abstract level and access to external services, such as Nextcloud or Dropbox, is done via lightweight drivers. It is easy to support new services by creating simple drivers that provide a filesystem-like interface, i.e. the ability to read, write, delete and list items. It is also simple to switch from one service to another or to even sync to multiple services at once. Each note, notebook, tags, as well as the relation between items is transmitted as plain text files during synchronisation, which means the data can also be moved to a different application, can be easily backed up, inspected, etc.
Currently, synchronisation is possible with Nextcloud, Dropbox, OneDrive or the local filesystem. To enable synchronisation please follow the instructions below. After that, the application will synchronise in the background whenever it is running, or you can click on "Synchronise" to start a synchronisation manually.
Currently, synchronisation is possible with Nextcloud, WebDAV, Dropbox, OneDrive or the local filesystem. To enable synchronisation please follow the instructions below. After that, the application will synchronise in the background whenever it is running, or you can click on "Synchronise" to start a synchronisation manually. Joplin will background sync automatically after any content change is made on the local application.
If the **terminal client** has been installed, it is possible to also synchronise outside of the user interface by typing `joplin sync` from the terminal. This can be used to setup a cron script to synchronise at a regular interval. For example, this would do it every 30 minutes:
` */30 * * * * /path/to/joplin sync`
## Nextcloud synchronisation
<img src="https://joplinapp.org/images/nextcloud-logo-background.png" width="100" align="left"> <a href="https://nextcloud.com/">Nextcloud</a> is a self-hosted, private cloud solution. It can store documents, images and videos but also calendars, passwords and countless other things and can sync them to your laptop or phone. As you can host your own Nextcloud server, you own both the data on your device and infrastructure used for synchronisation. As such it is a good fit for Joplin. The platform is also well supported and with a strong community, so it is likely to be around for a while - since it's open source anyway, it is not a service that can be closed, it can exist on a server for as long as one chooses.
In the **desktop application** or **mobile application**, go to the config screen and select Nextcloud as the synchronisation target. Then input the WebDAV URL (to get it, click on Settings in the bottom left corner of the page, in Nextcloud), this is normally `https://example.com/nextcloud/remote.php/webdav/Joplin` (**make sure to create the "Joplin" directory in Nextcloud**), and set the username and password. If it does not work, please [see this explanation](https://github.com/laurent22/joplin/issues/61#issuecomment-373282608) for more details.
In the **desktop application** or **mobile application**, go to the Configuration screen and select Nextcloud as the synchronisation target. Then input the WebDAV URL (to get it, click on Settings in the bottom left corner of the page, in Nextcloud), this is normally `https://example.com/nextcloud/remote.php/webdav/Joplin` (**make sure to create the "Joplin" directory in Nextcloud**), and set the username and password. If it does not work, please [see this explanation](https://github.com/laurent22/joplin/issues/61#issuecomment-373282608) for more details.
In the **terminal application**, you will need to set the `sync.target` config variable and all the `sync.5.path`, `sync.5.username` and `sync.5.password` config variables to, respectively the Nextcloud WebDAV URL, your username and your password. This can be done from the command line mode using:
@ -210,19 +224,9 @@ In the **terminal application**, you will need to set the `sync.target` config v
If synchronisation does not work, please consult the logs in the app profile directory - it is often due to a misconfigured URL or password. The log should indicate what the exact issue is.
## Dropbox synchronisation
When syncing with Dropbox, Joplin creates a sub-directory in Dropbox, in `/Apps/Joplin` and read/write the notes and notebooks from it. The application does not have access to anything outside this directory.
In the **desktop application** or **mobile application**, select "Dropbox" as the synchronisation target in the config screen (it is selected by default). Then, to initiate the synchronisation process, click on the "Synchronise" button in the sidebar and follow the instructions.
In the **terminal application**, to initiate the synchronisation process, type `:sync`. You will be asked to follow a link to authorise the application. It is possible to also synchronise outside of the user interface by typing `joplin sync` from the terminal. This can be used to setup a cron script to synchronise at regular interval. For example, this would do it every 30 minutes:
*/30 * * * * /path/to/joplin sync
## WebDAV synchronisation
Select the "WebDAV" synchronisation target and follow the same instructions as for Nextcloud above.
Select the "WebDAV" synchronisation target and follow the same instructions as for Nextcloud above (for the **terminal application** you will need to select sync target 6 rather than 5)
WebDAV-compatible services that are known to work with Joplin:
@ -239,11 +243,19 @@ WebDAV-compatible services that are known to work with Joplin:
- [WebDAV Nav](https://www.schimera.com/products/webdav-nav-server/), a macOS server.
- [Zimbra](https://www.zimbra.com/)
## Dropbox synchronisation
When syncing with Dropbox, Joplin creates a sub-directory in Dropbox, in `/Apps/Joplin` and read/write the notes and notebooks from it. The application does not have access to anything outside this directory.
In the **desktop application** or **mobile application**, select "Dropbox" as the synchronisation target in the Configuration screen (it is selected by default). Then, to initiate the synchronisation process, click on the "Synchronise" button in the sidebar and follow the instructions.
In the **terminal application**, to initiate the synchronisation process, type `:sync`. You will be asked to follow a link to authorise the application.
## OneDrive synchronisation
When syncing with OneDrive, Joplin creates a sub-directory in OneDrive, in /Apps/Joplin and read/write the notes and notebooks from it. The application does not have access to anything outside this directory.
In the **desktop application** or **mobile application**, select "OneDrive" as the synchronisation target in the config screen. Then, to initiate the synchronisation process, click on the "Synchronise" button in the sidebar and follow the instructions.
In the **desktop application** or **mobile application**, select "OneDrive" as the synchronisation target in the Configuration screen. Then, to initiate the synchronisation process, click on the "Synchronise" button in the sidebar and follow the instructions.
In the **terminal application**, to initiate the synchronisation process, type `:sync`. You will be asked to follow a link to authorise the application (simply input your Microsoft credentials - you do not need to register with OneDrive).
@ -257,9 +269,9 @@ For a more technical description, mostly relevant for development or to review t
The Joplin applications automatically save previous versions of your notes at regular intervals. These versions are synced across devices and can be viewed from the desktop application. To do so, click on the "Information" button on a note, then click on "Previous version of this note". From this screen you can view the previous versions of the note as well as restore any of them.
This feature can be disabled from the "Note history" section in the settings, and it is also possible to change for how long the history of a note is saved.
This feature can be disabled from the "Note history" section in the Configuration screen, and it is also possible to change for how long the history of a note is saved.
More information about this feature in the [announcement post](https://www.patreon.com/posts/note-history-now-27083082).
More information please see the [Note History page](https://github.com/laurent22/joplin/blob/dev/readme/note_history.md).
# External text editor
@ -267,7 +279,7 @@ Joplin notes can be opened and edited using an external editor of your choice. I
# Attachments
Any kind of file can be attached to a note. In Markdown, links to these files are represented as a simple ID to the attachment. In the note viewer, these files, if they are images, will be displayed or, if they are other files (PDF, text files, etc.) they will be displayed as links. Clicking on this link will open the file in the default application.
Any kind of file can be attached to a note. In Markdown, links to these files are represented as a simple ID to the attachment, clicking on this link will open the file in the default application. In the case of audio, video and pdf files, these will be displayed inline with the note and so can be viewed or played within Joplin.
In the **desktop application**, files can be attached either by clicking the "Attach file" icon in the editor or via drag and drop. If you prefer to create a link to a local file instead, hold the ALT key while performing the drag and drop operation. You can also copy and paste images directly in the editor via Ctrl+V.
@ -309,7 +321,7 @@ Joplin uses and renders a Github-flavoured Markdown with a few variations and ad
# Custom CSS
Rendered markdown can be customized by placing a userstyle file in the profile directory `~/.config/joplin-desktop/userstyle.css` (This path might be different on your device - check at the top of the Config screen for the exact path). This file supports standard CSS syntax. Joplin ***must*** be restarted for the new css to be applied, please ensure that Joplin is not closing to the tray, but is actually exiting. Note that this file is used for both displaying the notes and printing the notes. Be aware how the CSS may look printed (for example, printing white text over a black background is usually not wanted).
Rendered markdown can be customized by placing a userstyle file in the profile directory `~/.config/joplin-desktop/userstyle.css` (This path might be different on your device - check at the top of the `General` page of the Configuration menu for the exact path). This file supports standard CSS syntax. Joplin ***must*** be restarted for the new css to be applied, please ensure that Joplin is not closing to the tray, but is actually exiting. Note that this file is used for both displaying the notes and printing the notes. Be aware how the CSS may look printed (for example, printing white text over a black background is usually not wanted).
The whole UI can be customized by placing a custom editor style file in the profile directory `~/.config/joplin-desktop/userchrome.css`.
@ -317,7 +329,7 @@ Important: userstyle.css and userchrome.css are provided for your convenience, b
# Note templates
In the **desktop app**, templates can be used to create new notes or to insert into existing ones by creating a `templates` folder in Joplin's config folder and placing Markdown template files into it. For example creating the file `hours.md` in the `templates` directory with the contents:
In the **desktop app**, templates can be used to create new notes or to insert into existing ones by adding a template file to the `templates` directory (File > Templates). For example creating the file `hours.md` in the `templates` directory with the contents:
```markdown
Date: {{date}}
@ -338,6 +350,14 @@ The currently supported template variables are:
| `{{bowm}}` | Date of the beginning of the week (when week starts on Monday) based on the settings format | |
| `{{bows}}` | Date of the beginning of the week (when week starts on Sunday) based on the settings format | |
# Plugins
The **desktop app** has the ability to extend beyond its standard functionality by the way of plugins. These plugins adhere to the Joplin plugin API and can be installed & configured within the application via the `Plugins` page in the Configuration screen. This menu allows the manual installation of the plugin using the single 'Joplin Plugin Archive' (*.jpl) file. Once the application is reloaded the plugins will appear within the plugins menu where they can be toggled on/off or removed entirely.
Plugins are currently maintained by the community in the [Joplin Discourse 'plugins' category](https://discourse.joplinapp.org/c/plugins/18).
For more information see [Plugins](https://github.com/laurent22/joplin/blob/dev/readme/plugins.md)
# Searching
Joplin implements the SQLite Full Text Search (FTS4) extension. It means the content of all the notes is indexed in real time and search queries return results very fast. Both [Simple FTS Queries](https://www.sqlite.org/fts3.html#simple_fts_queries) and [Full-Text Index Queries](https://www.sqlite.org/fts3.html#full_text_index_queries) are supported. See below for the list of supported queries:

8
readme/faq.md
View File

@ -33,7 +33,7 @@ subl -n -w # Opens Sublime (subl) in a new window (-n) and waits for close
code -n --wait # Opens Visual Studio Code (code) in a new window (-n) and waits for close (--wait)
gedit --new-window # Opens gedit (Gnome Text Editor) in a new window
xterm -e vim # Opens a new terminal and opens vim. Can be replaced with an
# alternative terminal (gnome-terminal, terminator, etc.)
# alternative terminal (gnome-terminal, terminator, etc.)
# or terminal text-editor (emacs, nano, etc.)
open -a <application> # Mac only: opens a GUI application
```
@ -87,7 +87,7 @@ For these reasons, because the OS or yourself can easily protect the local data,
There is however an issue open about it, so pull requests are welcome: https://github.com/laurent22/joplin/issues/289
## WebDAV synchronisation is not working
## Why is my WebDAV host not working?
### "Forbidden" error in Strato
@ -104,6 +104,10 @@ For example:
In this case, [make sure you enter the correct WebDAV URL](https://github.com/laurent22/joplin/issues/309).
### The following WebDAV hosts are not supported
- Jianguoyun.com (see [Github issue](https://github.com/laurent22/joplin/issues/4294))
### Nextcloud sync is not working
- Check your username and password. **Type it manually** (without copying and pasting it) and try again.

2
readme/nextcloud_app.md
View File

@ -4,7 +4,7 @@
**IMPORTANT: THIS APPLICATION IS DEPRECATED AND WILL NO LONGER BE SUPPORTED FROM JOPLIN 1.6.x**
It is deprecated in favour of [Joplin Server](https://discourse.joplinapp.org/t/joplin-web-api-for-nextcloud/4491/72?u=laurent), so if you are relying on it please do not upgrade to Joplin 1.6.x till you are ready to migrate to Joplin Server or some other alternative.
It is [deprecated](https://discourse.joplinapp.org/t/joplin-web-api-for-nextcloud/4491/72?u=laurent) in favour of [Joplin Server](https://discourse.joplinapp.org/t/joplin-server-pre-release-is-now-available/13605), so if you are relying on it please do not upgrade to Joplin 1.6.x till you are ready to migrate to Joplin Server or some other alternative.
* * *

31
readme/note_history.md Normal file
View File

@ -0,0 +1,31 @@
# Note History
Joplin has support for note history. The applications (desktop, mobile and CLI) now preserve previous versions of the notes, so you can inspect or restore them later on as needed.
A common complain with many sync-based note taking apps is that they work in an opaque way - sometimes notes are changed or they disappear and it's not clear why - it could be a user error, or some bug, but regardless it makes it hard to trust the app with thousands of notes. So this feature give transparency over what's happening - if some note seems to be gone or changed when it shouldn't, the redundant data allows investigating the issue and restoring content.
Another medium term goal is to allow the implementation of a recycle bin. Behind the scene, this is essentially already done since whenever a note is deleted, a final revision of that note is preserved. What's missing is a user interface (i.e. the recycle bin) to view these deleted notes.
### How does it work?
All the apps save a version of the modified notes every 10 minutes. These revisions are then synced across all the devices so if you're looking for a particular version of a note that was made on mobile, you can later find that version on the desktop app too.
### How to view the history of a note?
While all the apps save revisions, currently only the desktop one allow viewing these revisions.
To do so, click on the Information icon in the toolbar, then select "Previous version of this note".
![](https://raw.githubusercontent.com/laurent22/joplin/dev/readme/blog/images/20190523-231026_0.png)
The next screen will show the latest version of the note. You can then choose to view a different version, if any, or to restore one of them.
To restore a note, simply click on the "Restore" button. The old version of the note will be copied in a folder called "Restored Notes". The current version of the note will not be replaced or modified.
![](https://raw.githubusercontent.com/laurent22/joplin/dev/readme/blog/images/20190523-231026_1.png)
### How to configure the note history feature?
Additional options are available in the `Note History` page of the Configuration screen. It is possible to enable/disable the note history feature. It is also possible to specify for how long the history of a note should be kept (by default, for 90 days).
**IMPORTANT**: Please note that since all the revisions are synced across all devices, it means these settings are kind of global. So for example, if on one device you set it to keep revisions for 30 days, and on another to 100 days, the revisions older than 30 days will be deleted, and then this deletion will be synced. So in practice it means revisions are kept for whatever is the minimum number of days as set on any of the devices. In that particular case, the 100 days setting will be essentially ignored, and only the 30 days one will apply.

24
readme/plugins.md
View File

@ -1,7 +1,27 @@
# Plugins
Joplin supports plugins, which can be used to add new features or modify the application behaviour.
The **desktop app** has the ability to extend beyond its standard functionality by the way of plugins. These plugins adhere to the Joplin plugin API and can be installed & configured within the application via the `Plugins` page of the Settings menu (*Windows/Linux*: Tools > Options > Plugins; *macOS*: Joplin > Preferences). This menu allows the manual installation of the plugin using the single 'Joplin Plugin Archive' (*.jpl) file. Once the application is reloaded the plugins will appear within the plugins menu where they can be toggled on/off or removed entirely.
## Plugin Repository
Plugins are currently maintained by the community in the [Joplin Discourse 'plugins' category](https://discourse.joplinapp.org/c/plugins/18).
## Installing a plugin
To install a plugin, copy its directory to your profile's `plugins` directory. The plugin will be automatically loaded and executed when you restart the application.
To install a plugin press the Install Plugin button within the `Plugins` page of the Configuration screen and select the *.jpl file. Alternatively you can copy the *.jpl to your profile's `plugins` directory directory `~/.config/joplin-desktop/plugins` (This path might be different on your device - check at the top of the `Options` page in the Configuration screen). The plugin will be automatically loaded and executed when you restart the application. You may need to check Joplin is not minimising to the system tray/notification area rather than fully closing.
## Managing Plugins
Within the Joplin Plugins page you have the option to turn individual plugins on or off using the toggle control. After changing the state of a plugin Joplin must be restarted, you may need to check Joplin is not minimising to the system tray/notification area rather than fully closing.
As the plugins integrate into the application itself, each plugin may have its own configuration options within Joplin and may be exectuted in a number of different ways. Ensure that you read the author's documentation fully to understand how each plugin is designed to be configured and used.
## Uninstalling plugins
Within the Joplin Plugins page you can hit the 'Delete' button on a plugin and it will be removed from the list. Joplin must be restarted for this to complete. You may need to check Joplin is not minimising to the system tray/notification area rather than fully closing.
Alternatively you can simply remove *.jpl from the plugin directory (see Installing a plugin section). The change will be reflected on application restart.
## Development
There is documentation of the plugin API along with documentation on plugin development. Check the [Joplin API Overview](https://github.com/laurent22/joplin/blob/dev/readme/api/overview.md) page for these items.

2
readme/rich_text_editor.md
View File

@ -18,4 +18,6 @@ However **there is a catch**: in Joplin, notes, even when edited with this Rich
- Special keyboard modes "vim" and "emacs" are not supported.
- If a note is of 'Markup - Markdown' and contains HTML formatting, this may be lost when editing in the Rich Text editor as it cannot be converted to Markdown. Notes of 'Markup - HTML' are not affected by edits in the Rich Rext editor as this conversion does not take place.
Those are the known limitations but if you notice any other issue not listed here, please let us know [in the forum](https://discourse.joplinapp.org/).

288
readme/terminal.md
View File

@ -105,9 +105,12 @@ To import Evernote data, follow these steps:
# Synchronisation
One of the goals of Joplin was to avoid being tied to any particular company or service, whether it is Evernote, Google or Microsoft. As such the synchronisation is designed without any hard dependency to any particular service. Most of the synchronisation process is done at an abstract level and access to external services, such as Nextcloud or OneDrive, is done via lightweight drivers. It is easy to support new services by creating simple drivers that provide a filesystem-like interface, i.e. the ability to read, write, delete and list items. It is also simple to switch from one service to another or to even sync to multiple services at once. Each note, notebook, tags, as well as the relation between items is transmitted as plain text files during synchronisation, which means the data can also be moved to a different application, can be easily backed up, inspected, etc.
One of the goals of Joplin was to avoid being tied to any particular company or service, whether it is Evernote, Google or Microsoft. As such the synchronisation is designed without any hard dependency to any particular service. Most of the synchronisation process is done at an abstract level and access to external services, such as Nextcloud or Dropbox, is done via lightweight drivers. It is easy to support new services by creating simple drivers that provide a filesystem-like interface, i.e. the ability to read, write, delete and list items. It is also simple to switch from one service to another or to even sync to multiple services at once. Each note, notebook, tags, as well as the relation between items is transmitted as plain text files during synchronisation, which means the data can also be moved to a different application, can be easily backed up, inspected, etc.
Currently, synchronisation is possible with Nextcloud, Dropbox (by default) and OneDrive, or the local filesystem. To setup synchronisation please follow the instructions below. After that, the application will synchronise in the background whenever it is running, or you can click on "Synchronise" to start a synchronisation manually.
Currently, synchronisation is possible with Nextcloud, WebDAV, Dropbox, OneDrive or the local filesystem. To enable synchronisation please follow the instructions below. After that, the application will synchronise in the background whenever it is running, or you can click on "Synchronise" to start a synchronisation manually. Joplin will background sync automatically after any content change is made on the local application.
If the **terminal client** has been installed, it is possible to also synchronise outside of the user interface by typing `joplin sync` from the terminal. This can be used to setup a cron script to synchronise at a regular interval. For example, this would do it every 30 minutes:
*/30 * * * * /path/to/joplin sync
## Nextcloud synchronisation
@ -122,15 +125,22 @@ If synchronisation does not work, please consult the logs in the app profile dir
## WebDAV synchronisation
Select the "WebDAV" synchronisation target and follow the same instructions as for Nextcloud above.
Select the "WebDAV" synchronisation target and follow the same instructions as for Nextcloud above (for the **terminal application** you will need to select sync target 6 rather than 5).
## OneDrive and Dropbox synchronisation
For WebDAV-compatible services that are known to work with Joplin see [WebDAV synchronisation](https://github.com/laurent22/joplin#webdav-synchronisation).
For Dropbox, type `:config sync.target 7`. For OneDrive, type `:config sync.target 3`. Then type `sync` to login to the service and start the synchronisation process.
It is possible to also synchronise outside of the user interface by typing `joplin sync` from the terminal. This can be used to setup a cron script to synchronise at regular interval. For example, this would do it every 30 minutes:
## Dropbox synchronisation
*/30 * * * * /path/to/joplin sync
When syncing with Dropbox, Joplin creates a sub-directory in Dropbox, in `/Apps/Joplin` and read/write the notes and notebooks from it. The application does not have access to anything outside this directory.
To initiate the synchronisation process, type `:sync`. You will be asked to follow a link to authorise the application.
## OneDrive synchronisation
When syncing with OneDrive, Joplin creates a sub-directory in OneDrive, in /Apps/Joplin and read/write the notes and notebooks from it. The application does not have access to anything outside this directory.
To initiate the synchronisation process, type `:sync`. You will be asked to follow a link to authorise the application (simply input your Microsoft credentials - you do not need to register with OneDrive).
# URLs
@ -269,193 +279,195 @@ The following commands are available in [command-line mode](#command-line-mode):
config [name] [value]
Gets or sets a config value. If [value] is not provided, it will show the
value of [name]. If neither [name] nor [value] is provided, it will list
Gets or sets a config value. If [value] is not provided, it will show the
value of [name]. If neither [name] nor [value] is provided, it will list
the current configuration.
-v, --verbose Also displays unset and hidden config variables.
--export Writes all settings to STDOUT as JSON including
--export Writes all settings to STDOUT as JSON including
secure variables.
--import Reads in JSON formatted settings from STDIN.
--import-file <file> Reads in settings from <file>. <file> must contain
--import-file <file> Reads in settings from <file>. <file> must contain
valid JSON.
Possible keys/values:
sync.target Synchronisation target.
The target to synchonise to. Each sync
target may have additional parameters which
are named as `sync.NUM.NAME` (all
The target to synchonise to. Each sync
target may have additional parameters which
are named as `sync.NUM.NAME` (all
documented below).
Type: Enum.
Possible values: 2 (File system), 3
(OneDrive), 4 (OneDrive Dev (For testing
only)), 5 (Nextcloud), 6 (WebDAV), 7
Possible values: 2 (File system), 3
(OneDrive), 4 (OneDrive Dev (For testing
only)), 5 (Nextcloud), 6 (WebDAV), 7
(Dropbox).
Default: 7
sync.2.path Directory to synchronise with (absolute
sync.2.path Directory to synchronise with (absolute
path).
Attention: If you change this location,
make sure you copy all your content to it
before syncing, otherwise all files will be
removed! See the FAQ for more details:
Attention: If you change this location,
make sure you copy all your content to it
before syncing, otherwise all files will be
removed! See the FAQ for more details:
https://joplinapp.org/faq/
Type: string.
sync.5.path Nextcloud WebDAV URL.
Attention: If you change this location,
make sure you copy all your content to it
before syncing, otherwise all files will be
removed! See the FAQ for more details:
Attention: If you change this location,
make sure you copy all your content to it
before syncing, otherwise all files will be
removed! See the FAQ for more details:
https://joplinapp.org/faq/
Type: string.
sync.5.username Nextcloud username.
Type: string.
sync.5.password Nextcloud password.
Type: string.
sync.6.path WebDAV URL.
Attention: If you change this location,
make sure you copy all your content to it
before syncing, otherwise all files will be
removed! See the FAQ for more details:
Attention: If you change this location,
make sure you copy all your content to it
before syncing, otherwise all files will be
removed! See the FAQ for more details:
https://joplinapp.org/faq/
Type: string.
sync.6.username WebDAV username.
Type: string.
sync.6.password WebDAV password.
Type: string.
sync.maxConcurrentConnections Max concurrent connections.
Type: int.
Default: 5
locale Language.
Please see localisation section on
https://joplinapp.org/#localisation
for info on translation completion progress
Type: Enum.
Possible values: ar (Arabic (92%)), eu
(Basque (39%)), bs_BA (Bosnian (85%)),
bg_BG (Bulgarian (77%)), ca (Catalan
(61%)), hr_HR (Croatian (32%)), cs_CZ
(Czech (94%)), da_DK (Dansk (85%)), de_DE
(Deutsch (100%)), et_EE (Eesti Keel (76%)),
en_GB (English (UK) (100%)), en_US (English
(US) (100%)), es_ES (Español (95%)), eo
(Esperanto (44%)), fr_FR (Français (95%)),
gl_ES (Galician (50%)), it_IT (Italiano
(97%)), nl_BE (Nederlands (39%)), nl_NL
(Nederlands (97%)), nb_NO (Norwegian
(89%)), fa (Persian (38%)), pl_PL (Polski
(75%)), pt_PT (Português (91%)), pt_BR
(Português (Brasil) (88%)), ro (Română
(39%)), sl_SI (Slovenian (49%)), sv
(Svenska (68%)), tr_TR (Türkçe (92%)),
el_GR (Ελληνικά (93%)), ru_RU (Русский
(95%)), sr_RS (српски језик (75%)), zh_CN
(中文 (简体) (97%)), zh_TW (中文 (繁體) (91%)),
ja_JP (日本語 (97%)), ko (한국말 (97%)).
Possible values: ar (Arabic), eu (Basque),
bs_BA (Bosnian), bg_BG (Bulgarian),
ca (Catalan), hr_HR (Croatian),
cs_CZ (Czech), da_DK (Dansk),
de_DE (Deutsch), et_EE (Eesti Keel),
en_GB (English (UK)), en_US (English (US)),
es_ES (Español), eo (Esperanto),
fi_FI (Finnish), fr_FR (Français),
gl_ES (Galician), id_ID (Indonesian),
it_IT (Italiano), nl_BE (Nederlands),
nl_NL (Nederlands), nb_NO (Norwegian),
fa (Persian), pl_PL (Polski),
pt_PT (Português),
pt_BR (Português (Brasil)), ro (Română),
sl_SI (Slovenian), sv (Svenska),
th_TH (Thai), vi (Tiếng Việt),
tr_TR (Türkçe), el_GR (Ελληνικά),
ru_RU (Русский), sr_RS (српски језик),
zh_CN (中文 (简体)), zh_TW (中文 (繁體)),
ja_JP (日本語), ko (한국말).
Default: "en_GB"
dateFormat Date format.
Type: Enum.
Possible values: DD/MM/YYYY (30/01/2017),
DD/MM/YY (30/01/17), MM/DD/YYYY
(01/30/2017), MM/DD/YY (01/30/17),
YYYY-MM-DD (2017-01-30), DD.MM.YYYY
Possible values: DD/MM/YYYY (30/01/2017),
DD/MM/YY (30/01/17), MM/DD/YYYY
(01/30/2017), MM/DD/YY (01/30/17),
YYYY-MM-DD (2017-01-30), DD.MM.YYYY
(30.01.2017), YYYY.MM.DD (2017.01.30).
Default: "DD/MM/YYYY"
timeFormat Time format.
Type: Enum.
Possible values: HH:mm (20:30), h:mm A
Possible values: HH:mm (20:30), h:mm A
(8:30 PM).
Default: "HH:mm"
uncompletedTodosOnTop Uncompleted to-dos on top.
Type: bool.
Default: true
showCompletedTodos Show completed to-dos.
Type: bool.
Default: true
notes.sortOrder.field Sort notes by.
Type: Enum.
Possible values: user_updated_time (Updated
date), user_created_time (Created date),
Possible values: user_updated_time (Updated
date), user_created_time (Created date),
title (Title).
Default: "user_updated_time"
notes.sortOrder.reverse Reverse sort order.
Type: bool.
Default: true
folders.sortOrder.field Sort notebooks by.
Type: Enum.
Possible values: title (Title),
Possible values: title (Title),
last_note_user_updated_time (Updated date).
Default: "title"
folders.sortOrder.reverse Reverse sort order.
Type: bool.
Default: false
trackLocation Save geo-location with notes.
Type: bool.
Default: true
sync.interval Synchronisation interval.
Type: Enum.
Possible values: 0 (Disabled), 300 (5
minutes), 600 (10 minutes), 1800 (30
minutes), 3600 (1 hour), 43200 (12 hours),
Possible values: 0 (Disabled), 300 (5
minutes), 600 (10 minutes), 1800 (30
minutes), 3600 (1 hour), 43200 (12 hours),
86400 (24 hours).
Default: 300
editor Text editor command.
The editor command (may include arguments)
that will be used to open a note. If none
is provided it will try to auto-detect the
The editor command (may include arguments)
that will be used to open a note. If none
is provided it will try to auto-detect the
default editor.
Type: string.
net.customCertificates Custom TLS certificates.
Comma-separated list of paths to
directories to load the certificates from,
or path to individual cert files. For
example: /my/cert_dir, /other/custom.pem.
Note that if you make changes to the TLS
settings, you must save your changes before
clicking on "Check synchronisation
Comma-separated list of paths to
directories to load the certificates from,
or path to individual cert files. For
example: /my/cert_dir, /other/custom.pem.
Note that if you make changes to the TLS
settings, you must save your changes before
clicking on "Check synchronisation
configuration".
Type: string.
net.ignoreTlsErrors Ignore TLS certificate errors.
Type: bool.
Default: false
sync.wipeOutFailSafe Fail-safe: Do not wipe out local data when
sync target is empty (often the result of a
sync.wipeOutFailSafe Fail-safe: Do not wipe out local data when
sync target is empty (often the result of a
misconfiguration or bug).
Type: bool.
Default: true
revisionService.enabled Enable note history.
Type: bool.
Default: true
revisionService.ttlDays Keep note history for.
Type: int.
Default: 90
cp <note> [notebook]
Duplicates the notes matching <note> to [notebook]. If no notebook is
Duplicates the notes matching <note> to [notebook]. If no notebook is
specified the note is duplicated in the current notebook.
done <note>
@ -464,13 +476,13 @@ The following commands are available in [command-line mode](#command-line-mode):
e2ee <command> [path]
Manages E2EE configuration. Commands are `enable`, `disable`, `decrypt`,
Manages E2EE configuration. Commands are `enable`, `disable`, `decrypt`,
`status`, `decrypt-file` and `target-status`.
-p, --password <password> Use this password as master password (For
security reasons, it is not recommended to use
-p, --password <password> Use this password as master password (For
security reasons, it is not recommended to use
this option).
-v, --verbose More verbose output for the `target-status`
-v, --verbose More verbose output for the `target-status`
command
-o, --output <directory> Output directory
@ -480,12 +492,12 @@ The following commands are available in [command-line mode](#command-line-mode):
export <path>
Exports Joplin data to the given path. By default, it will export the
Exports Joplin data to the given path. By default, it will export the
complete database including notebooks, notes, tags and resources.
--format <format> Destination format: jex (Joplin Export File), raw
(Joplin Export Directory), json (Json Export
Directory), md (Markdown), html (HTML File), html
--format <format> Destination format: jex (Joplin Export File), raw
(Joplin Export Directory), json (Json Export
Directory), md (Markdown), html (HTML File), html
(HTML Directory)
--note <note> Exports only the given note.
--notebook <notebook> Exports only the given notebook.
@ -507,20 +519,20 @@ The following commands are available in [command-line mode](#command-line-mode):
ls [note-pattern]
Displays the notes in the current notebook. Use `ls /` to display the list
Displays the notes in the current notebook. Use `ls /` to display the list
of notebooks.
-n, --limit <num> Displays only the first top <num> notes.
-s, --sort <field> Sorts the item by <field> (eg. title, updated_time,
-s, --sort <field> Sorts the item by <field> (eg. title, updated_time,
created_time).
-r, --reverse Reverses the sorting order.
-t, --type <type> Displays only the items of the specific type(s).
Can be `n` for notes, `t` for to-dos, or `nt` for
notes and to-dos (eg. `-tt` would display only the
to-dos, while `-ttd` would display notes and
-t, --type <type> Displays only the items of the specific type(s).
Can be `n` for notes, `t` for to-dos, or `nt` for
notes and to-dos (eg. `-tt` would display only the
to-dos, while `-ttd` would display notes and
to-dos.
-f, --format <format> Either "text" or "json"
-l, --long Use long list format. Format is ID, NOTE_COUNT (for
-l, --long Use long list format. Format is ID, NOTE_COUNT (for
notebook), DATE, TODO_CHECKED (for to-dos), TITLE
mkbook <new-notebook>
@ -557,24 +569,24 @@ The following commands are available in [command-line mode](#command-line-mode):
server <command>
Start, stop or check the API server. To specify on which port it should
run, set the api.port config variable. Commands are (start|stop|status).
This is an experimental feature - use at your own risks! It is recommended
that the server runs off its own separate profile so that no two CLI
instances access that profile at the same time. Use --profile to specify
Start, stop or check the API server. To specify on which port it should
run, set the api.port config variable. Commands are (start|stop|status).
This is an experimental feature - use at your own risks! It is recommended
that the server runs off its own separate profile so that no two CLI
instances access that profile at the same time. Use --profile to specify
the profile path.
set <note> <name> [value]
Sets the property <name> of the given <note> to the given [value].
Sets the property <name> of the given <note> to the given [value].
Possible properties are:
parent_id (text), title (text), body (text), created_time (int),
updated_time (int), is_conflict (int), latitude (numeric), longitude
(numeric), altitude (numeric), author (text), source_url (text), is_todo
(int), todo_due (int), todo_completed (int), source (text),
source_application (text), application_data (text), order (int),
user_created_time (int), user_updated_time (int), encryption_cipher_text
parent_id (text), title (text), body (text), created_time (int),
updated_time (int), is_conflict (int), latitude (numeric), longitude
(numeric), altitude (numeric), author (text), source_url (text), is_todo
(int), todo_due (int), todo_completed (int), source (text),
source_application (text), application_data (text), order (int),
user_created_time (int), user_updated_time (int), encryption_cipher_text
(text), encryption_applied (int), markup_language (int), is_shared (int)
status
@ -585,24 +597,24 @@ The following commands are available in [command-line mode](#command-line-mode):
Synchronises with remote storage.
--target <target> Sync to provided target (defaults to sync.target config
--target <target> Sync to provided target (defaults to sync.target config
value)
tag <tag-command> [tag] [note]
<tag-command> can be "add", "remove", "list", or "notetags" to assign or
remove [tag] from [note], to list notes associated with [tag], or to list
tags associated with [note]. The command `tag list` can be used to list
<tag-command> can be "add", "remove", "list", or "notetags" to assign or
remove [tag] from [note], to list notes associated with [tag], or to list
tags associated with [note]. The command `tag list` can be used to list
all the tags (use -l for long option).
-l, --long Use long list format. Format is ID, NOTE_COUNT (for notebook),
-l, --long Use long list format. Format is ID, NOTE_COUNT (for notebook),
DATE, TODO_CHECKED (for to-dos), TITLE
todo <todo-command> <note-pattern>
<todo-command> can either be "toggle" or "clear". Use "toggle" to toggle
the given to-do between completed and uncompleted state (If the target is
a regular note it will be converted to a to-do). Use "clear" to convert
<todo-command> can either be "toggle" or "clear". Use "toggle" to toggle
the given to-do between completed and uncompleted state (If the target is
a regular note it will be converted to a to-do). Use "clear" to convert
the to-do back to a regular note.
undone <note>
@ -611,7 +623,7 @@ The following commands are available in [command-line mode](#command-line-mode):
use <notebook>
Switches to [notebook] - all further operations will happen within this
Switches to [notebook] - all further operations will happen within this
notebook.
version
@ -620,7 +632,7 @@ The following commands are available in [command-line mode](#command-line-mode):
# License
Copyright (c) 2016-2020 Laurent Cozic
Copyright (c) 2016-2021 Laurent Cozic
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

4
readme/welcome/3_synchronising_your_notes.md
View File

@ -16,8 +16,8 @@ To set it up, go to the config screen and select Nextcloud as the synchronisatio
## Setting up OneDrive or WebDAV synchronisation
OneDrive and WebDAV are also supported as synchronisation services. Please see [the export documentation](https://github.com/laurent22/joplin#exporting) for more information.
OneDrive and WebDAV are also supported as synchronisation services. Please see [the synchronisation documentation](https://github.com/laurent22/joplin#synchronisation) for more information.
## Using End-To-End Encryption
Joplin supports end-to-end encryption (E2EE) on all the applications. E2EE is a system where only the owner of the data can read it. It prevents potential eavesdroppers - including telecom providers, internet providers, and even the developers of Joplin from being able to access the data. Please see the [End-To-End Encryption Tutorial](https://joplinapp.org/e2ee/) for more information about this feature and how to enable it.
Joplin supports end-to-end encryption (E2EE) on all the applications. E2EE is a system where only the owner of the data can read it. It prevents potential eavesdroppers - including telecom providers, internet providers, and even the developers of Joplin from being able to access the data. Please see the [End-To-End Encryption Tutorial](https://joplinapp.org/e2ee/) for more information about this feature and how to enable it.