Improve docs

Signed-off-by: Axel Dürkop <[email protected]>
Signed-off-by: Tao Lin <[email protected]>

Author: xldrkp

README.md

@@ -10,64 +10,55 @@ For more background, see the initial [discussion](https://github.com/hackmdio/co
 ## Install
 
 Dependencies:
- - A HedgeDoc server running somewhere
- - `curl` (install via `apt install curl` or `brew install curl` on Mac)
- - `wget` (install via `apt install wget` or `brew install wget` on Mac)
- - `jq` (install via `apt install jq` or `brew install jq` on Mac)
+
+- A HedgeDoc server running somewhere
+- `curl` (install via `apt install curl` or `brew install curl` on Mac)
+- `wget` (install via `apt install wget` or `brew install wget` on Mac)
+- `jq` (install via `apt install jq` or `brew install jq` on Mac)
 
 ```bash
 git clone https://github.com/hedgedoc/cli
 cd cli/bin
 # optionally symlink the hedgedoc script somewhere into your $PATH
+# might need admin rights (sudo)
 ln -s $PWD/hedgedoc /usr/local/bin/hedgedoc
 
+# check if the new command exists. You should see the documentation 
+hedgedoc
+
 # set HEDGEDOC_SERVER environment variable to your server's URL
 # it defaults to http://127.0.0.1:3000
+# do this in .profile and/or .bashrc
 export HEDGEDOC_SERVER='https://hedgedoc.example.com'  
+# log out and in again to the terminal to read the new variable
 
-# Test by creating a new note
-hedgedoc login --email
+# Test by creating a new note with FREELY access, no login required
+# You will receive the generated hash for the document
+# Caution: You won't have the right to delete the new document!
+echo "# HedgeDoc!" > test.md
 hedgedoc import test.md
-```
-
-## Documentation
 
-### Create/import a new note
-```bash
-$ hedgedoc import <input_path> [note_id]     # takes a local path to a text file, and an optional note id for the new note
-qhmNmwmxSmK1H2oJmkKBQQ                     # returns <note_id> on success
+# check for the document in the browser by concatenating the
+# address of your server and the hash
 ```
 
-You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`.
+## Documentation
 
-The optional `note_id` is only available on servers with `allowFreeURL`
-enabled.
-Check the [documentation](https://docs.hedgedoc.org/configuration/#users-and-privileges)
-for more information.
+It's not necessary to authenticate against the server in order to use `hedgedoc-cli`. But without authentication you won't have access to the non-FREELY documents and everything that's accessible behind the login.
 
-### Publish an existing note
+### Variants of authentication
 
-```bash
-$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ   # takes a <note_id>
-S1ok9no3f                                 # returns public note id
-```
-You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`.
+#### Authenticate with cookie
 
-### Export an existing note
+Authentication with a cookie is so far the only way if you login with GitLab and the like. Use browser extensions like [Get cookies.txt](https://chrome.google.com/webstore/detail/get-cookiestxt/bgaddhkoddajcdgocldbbfleckgcbcid) to store the cookie in `key.conf`.
 
-```bash
-$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ             # takes a <note_id>, outputs to <note_id>.pdf by default
-$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md   # or you can specify an output path explicitly
-$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ
-$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip
-```
+Possible you have many lines in `key.conf`. You only need the line with `connect.sid` followed by a long hash!
 
-### Authenticate and get notes history
+Optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify where cookies will be stored. It defaults to `~/.config/hedgedoc/key.conf`
 
 ```bash
-# optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify
-# where cookies will be stored. It defaults to ~/.config/hedgedoc-cli/key.conf
-$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc-cli/key.conf
+# You can put this in .profile and/or .bashrc, too.
+$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc/key.conf
 ```
 #### Authenticate with email
 
@@ -83,7 +74,11 @@ $ hedgedoc login --ldap username p4sW0rD            # takes a username and a pas
 $ hedgedoc login --ldap                             # or pass them via stdin prompt instead
 ```
 
-#### Get auth status, history, and logout
+#### Check if authentication works
+
+If your authentication method is set up correctly the following commands will work.
+
+### Get auth status, history, and logout
 
 ```bash
 $ hedgedoc profile
@@ -110,6 +105,36 @@ You may need to log in again if:
  - your session expired
  - the hedgedoc server was restarted (which force-expires all sessions as a side-effect)
  - the  is`$HEDGEDOC_COOKIES_FILE` deleted, moved, or becomes unreadable by `hedgedoc-cli`
+### Create/import a new note
+```bash
+$ hedgedoc import <input_path> [note_id]     # takes a local path to a text file, and an optional note id for the new note
+qhmNmwmxSmK1H2oJmkKBQQ                     # returns <note_id> on success
+```
+
+You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`.
+
+The optional `note_id` is only available on servers with `allowFreeURL`
+enabled.
+Check the [documentation](https://docs.hedgedoc.org/configuration/#users-and-privileges)
+for more information.
+
+### Publish an existing note
+
+```bash
+$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ   # takes a <note_id>
+S1ok9no3f                                 # returns public note id
+```
+You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`.
+
+### Export an existing note
+
+```bash
+$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ             # takes a <note_id>, outputs to <note_id>.pdf by default
+$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md   # or you can specify an output path explicitly
+$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ
+$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip
+```
+
 
 ## API Endpoints