Skip to content

Commit 091b375

Browse files
davidmehrendavidmehren
authored
Merge pull request #49 from xldrkp/fix-docs
2 parents b2d17a3 + e06f894 commit 091b375

File tree

1 file changed

+84
-49
lines changed

1 file changed

+84
-49
lines changed

‎README.md‎

Lines changed: 84 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,67 +7,66 @@ For more background, see the initial [discussion](https://github.com/hackmdio/co
77
*There is an alternative, TypeScript-based CodiMD CLI for `hackmdio/codimd` maintained by the HackMD team here: https://github.com/hackmdio/codimd-cli.*
88
*(it may or may not be compatible with the `hedgedoc/hedgedoc` server)*
99

10-
## Install
10+
## Installation
1111

12-
Dependencies:
13-
- A HedgeDoc server running somewhere
14-
- `curl` (install via `apt install curl` or `brew install curl` on Mac)
15-
- `wget` (install via `apt install wget` or `brew install wget` on Mac)
16-
- `jq` (install via `apt install jq` or `brew install jq` on Mac)
12+
### Dependencies
1713

18-
```bash
19-
git clone https://github.com/hedgedoc/cli
20-
cd cli/bin
21-
# optionally symlink the hedgedoc script somewhere into your $PATH
22-
ln -s $PWD/hedgedoc /usr/local/bin/hedgedoc
23-
24-
# set HEDGEDOC_SERVER environment variable to your server's URL
25-
# it defaults to http://127.0.0.1:3000
26-
export HEDGEDOC_SERVER='https://hedgedoc.example.com'
27-
28-
# Test by creating a new note
29-
hedgedoc login --email
30-
hedgedoc import test.md
31-
```
14+
- A HedgeDoc server running somewhere
15+
- `curl` (install via `apt install curl` or `brew install curl` on Mac)
16+
- `wget` (install via `apt install wget` or `brew install wget` on Mac)
17+
- `jq` (install via `apt install jq` or `brew install jq` on Mac)
3218

33-
## Documentation
19+
### Instructions
3420

35-
### Create/import a new note
36-
```bash
37-
$ hedgedoc import <input_path> [note_id] # takes a local path to a text file, and an optional note id for the new note
38-
qhmNmwmxSmK1H2oJmkKBQQ # returns <note_id> on success
39-
```
21+
Clone the repository.
4022

41-
You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`.
23+
$ git clone https://github.com/hedgedoc/cli
4224

43-
The optional `note_id` is only available on servers with `allowFreeURL`
44-
enabled.
45-
Check the [documentation](https://docs.hedgedoc.org/configuration/#users-and-privileges)
46-
for more information.
25+
Enter the folder with the script.
4726

48-
### Publish an existing note
27+
$ cd cli/bin
4928

50-
```bash
51-
$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>
52-
S1ok9no3f # returns public note id
53-
```
54-
You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`.
29+
Optionally symlink the hedgedoc script somewhere into your $PATH to make it globally accessible. Otherwise you will have to provide the path to the script manually. This command might need admin rights (sudo)!
5530

56-
### Export an existing note
31+
$ ln -s $PWD/hedgedoc /usr/local/bin/hedgedoc
5732

58-
```bash
59-
$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>, outputs to <note_id>.pdf by default
60-
$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md # or you can specify an output path explicitly
61-
$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ
62-
$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip
63-
```
33+
Check if the new command exists. You should see the documentation
34+
35+
$ hedgedoc
36+
37+
Set `HEDGEDOC_SERVER` environment variable to your server's URL. It defaults to `http://127.0.0.1:3000` Do this once on the command line or persist it in `.profile` and/or `.bashrc`.
38+
39+
$ export HEDGEDOC_SERVER='https://hedgedoc.example.com'
40+
41+
If you added the variable to `.profile` or `.bashrc`, re-open the terminal to read the new variable.
42+
43+
Test your configuration by creating a new note with FREELY access and no login required. You will receive the generated `<note_id>` for the document like `3jXcabSfSNesbH6KT72ieg`.
44+
45+
**Caution: You won't have the right to delete the new document if not authenticated!**
46+
47+
$ echo "# HedgeDoc!" > test.md
48+
$ hedgedoc import test.md
49+
50+
Check for the document in the browser by concatenating the
51+
address of your server and the `<note_id>`.
52+
53+
## Configuration and usage
54+
55+
### Variants of authentication
56+
57+
It's not necessary to authenticate against the server in order to make use of `hedgedoc-cli`. But without authentication you won't have access to the non-FREELY documents and everything that's accessible behind the login.
58+
59+
#### Authenticate with cookie
6460

65-
### Authenticate and get notes history
61+
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`.
62+
63+
Possible you have many lines in `key.conf`. You only need the line with `connect.sid` followed by a long hash!
64+
65+
Optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify where cookies will be stored. It defaults to `~/.config/hedgedoc/key.conf`
6666

6767
```bash
68-
# optionally add the HEDGEDOC_COOKIES_FILE environment variable to specify
69-
# where cookies will be stored. It defaults to ~/.config/hedgedoc-cli/key.conf
70-
$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc-cli/key.conf
68+
# You can put this in .profile and/or .bashrc, too.
69+
$ export HEDGEDOC_COOKIES_FILE=~/.config/hedgedoc/key.conf
7170
```
7271
#### Authenticate with email
7372

@@ -83,7 +82,11 @@ $ hedgedoc login --ldap username p4sW0rD # takes a username and a pas
8382
$ hedgedoc login --ldap # or pass them via stdin prompt instead
8483
```
8584

86-
#### Get auth status, history, and logout
85+
#### Check if authentication works
86+
87+
If your authentication method is set up correctly the following commands will work.
88+
89+
### Get auth status, history, and logout
8790

8891
```bash
8992
$ hedgedoc profile
@@ -111,6 +114,38 @@ You may need to log in again if:
111114
- the hedgedoc server was restarted (which force-expires all sessions as a side-effect)
112115
- the is`$HEDGEDOC_COOKIES_FILE` deleted, moved, or becomes unreadable by `hedgedoc-cli`
113116

117+
### Create/import a new note
118+
119+
```bash
120+
$ hedgedoc import <input_path> [note_id] # takes a local path to a text file, and an optional note id for the new note
121+
qhmNmwmxSmK1H2oJmkKBQQ # returns <note_id> on success
122+
```
123+
124+
You can open the new note on the server by going to `$HEDGEDOC_SERVER/<note_id>`.
125+
126+
The optional `note_id` is only available on servers with `allowFreeURL`
127+
enabled.
128+
Check the [documentation](https://docs.hedgedoc.org/configuration/#users-and-privileges)
129+
for more information.
130+
131+
### Publish an existing note
132+
133+
```bash
134+
$ hedgedoc publish qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>
135+
S1ok9no3f # returns public note id
136+
```
137+
You can open the published note on the server by going to `$HEDGEDOC_SERVER/s/<public_note_id>`.
138+
139+
### Export an existing note
140+
141+
```bash
142+
$ hedgedoc export --pdf qhmNmwmxSmK1H2oJmkKBQQ # takes a <note_id>, outputs to <note_id>.pdf by default
143+
$ hedgedoc export --md qhmNmwmxSmK1H2oJmkKBQQ my_note.md # or you can specify an output path explicitly
144+
$ hedgedoc export --html qhmNmwmxSmK1H2oJmkKBQQ
145+
$ hedgedoc export --slides qhmNmwmxSmK1H2oJmkKBQQ my_slides.zip
146+
```
147+
148+
114149
## API Endpoints
115150

116151
These server endpoints are used by this project and can be unstable and undocumented, but may be of use if you're developing your own projects that need API access to HedgeDoc.

0 commit comments

Comments
 (0)