mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2025-05-17 08:34:54 -04:00
docs: restructure
This commit is contained in:
Erik Michelson
Erik Michelson
parent
91ebd519a8
commit
70a6583fe0
69 changed files with 471 additions and 385 deletions
5
docs/content/getting-started/explore.md
Normal file
5
docs/content/getting-started/explore.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Explore notes
|
||||
|
||||
TODO: This pages is still missing some content.
|
||||
See this issue for more information and if you want to contribute:
|
||||
<https://github.com/hedgedoc/hedgedoc/issues/4830>
|
||||
152
docs/content/getting-started/first-note.md
Normal file
152
docs/content/getting-started/first-note.md
Normal file
|
|
@ -0,0 +1,152 @@
|
|||
# Create your first note
|
||||
|
||||
We assume that you followed the previous tutorials for setting up an instance of HedgeDoc
|
||||
and created an user account.
|
||||
We assume the domain you use for the instance is <https://hedgedoc.localhost>, so please
|
||||
substitute it with your actual domain anywhere you encounter <https://hedgedoc.localhost>
|
||||
if that differs.
|
||||
|
||||
## Creating a new note
|
||||
|
||||
1. Go to <https://hedgedoc.localhost> and log in. You should now be on the "explore page" within the
|
||||
"My notes" section.
|
||||
|
||||
2. Click on the "New Note" button in the top right. HedgeDoc will now create a new
|
||||
note for you and redirect you to the editor of this note.
|
||||
![New Note button in the top right of the page][new-note]{ width="400" }
|
||||
|
||||
3. You are now in the editor, the main component of HedgeDoc. Let's explore the different parts of
|
||||
it now.
|
||||
|
||||
## The editor
|
||||
|
||||
![Editor view with different sections numbered and highlighted in color][editor]{ width="700" }
|
||||
|
||||
1. **Editor pane:** You will write your note contents here on the left side.
|
||||
Notes are written in Markdown syntax.
|
||||
2. **Renderer pane:** The renderer pane on the right contains the rendered output from the markdown
|
||||
on the left side.
|
||||
3. **View mode selection:** You can choose if you want to see only the editor pane, only the
|
||||
renderer pane or both panes (the default). This setting will be remembered for future visits.
|
||||
4. **Pane split resizer:** Use the little arrow handle in the middle to resize the split between
|
||||
editor pane and renderer pane by dragging it to the left or right.
|
||||
You can always reset the split by clicking the middle *view mode selector (3)*.
|
||||
5. **Editor toolbar:** The toolbar contains buttons to quickly insert markdown fragments into the
|
||||
editor at your current cursor position. It has buttons to upload an image or opening an
|
||||
emoji-picker too.
|
||||
6. **Editor statusbar:** The statusbar contains information about the current cursor position,
|
||||
selection and the note length.
|
||||
7. **Sidebar:** The sidebar contains all the important functionality to manage your note.
|
||||
There's for example the list of currently online people, the permission management, the
|
||||
possibility of importing or exporting the note content, and much more.
|
||||
|
||||
## Writing markdown
|
||||
|
||||
Start by writing a few things in the editor pane on the left side.
|
||||
You will see the same content in the renderer pane on the right side.
|
||||
|
||||
Markdown uses a few characters to control how the output looks. One of them is the hashtag (#).
|
||||
When written at the beginning of a line, the following text is treated as a heading.
|
||||
|
||||
There are several more such control characters, so just copy the example below into the editor,
|
||||
to get a first gist about them:
|
||||
|
||||
```markdown
|
||||
# A heading
|
||||
|
||||
## Another heading, but one level more nested
|
||||
|
||||
Some **bold**, *italic*, and ~~strokethrough~~ text.
|
||||
|
||||
- A bullet point list
|
||||
- ... which can be ...
|
||||
- nested as well
|
||||
- into multiple levels.
|
||||
|
||||
1. There are ...
|
||||
2. numbered lists too.
|
||||
|
||||
[This is a link](https://www.example.com).
|
||||
And this is a picture: .
|
||||
```
|
||||
|
||||
The result should look like this:
|
||||
|
||||
![Editor with the example from above][editor-text]{ width="700" }
|
||||
|
||||
You might have seen that the title in the middle of the top bar now says "A heading" instead of
|
||||
"Untitled". If not specified otherwise, the first heading of your note is used as the title of
|
||||
the note.
|
||||
|
||||
There's a whole lot more of things you can add to your note, from to-do lists, tables, flowcharts,
|
||||
to UML diagrams or simple sheet music. To discover the syntax for all these things, please refer
|
||||
to the *Cheatsheet*. It can be opened from the "Help menu", which opens when clicking the little
|
||||
button with the question mark at the top right.
|
||||
|
||||
## Collaborate on the note
|
||||
|
||||
You might have seen that the URL now looks like this:
|
||||
`https://hedgedoc.localhost/n/a2gra3bsstrjjy5w0dk2k1q3y0`.
|
||||
|
||||
Each new note receives an unique identifier, that is added to the URL.
|
||||
You can share this URL with other people to work collaboratively with them.
|
||||
Changes done by one user are applied in realtime to all other users as well.
|
||||
There's no limit on how many users can participate on a note.
|
||||
|
||||
By default, users that also have an account on your instance have write access, while non-logged-in
|
||||
users only have read access.
|
||||
You can manage these permissions on a more granular basis, see the
|
||||
[section about permissions](#setting-permissions) below.
|
||||
|
||||
When another user with write access joins your note, you see their cursor too.
|
||||
Each person has another color, so it is easier to distinguish between multiple ones.
|
||||
|
||||
![Screenshot of the editor with another person's cursor][collaboration]{ width="700" }
|
||||
|
||||
If you click the little icon with the persons in the sidebar, you get a list of the users which are
|
||||
currently working alongside you in the note. A little indicator circle next to the name shows
|
||||
whether the user currently has the editor focused (green) or not (red). This way you can quickly see
|
||||
who's actively writing in the moment.
|
||||
|
||||
## Setting permissions
|
||||
|
||||
By clicking the little lock icon in the sidebar, you open the permissions management dialog.
|
||||
This allows you to configure who has access to your note, and especially who has write access and
|
||||
who only read access.
|
||||
|
||||
![Screenshot of the permissions management dialog][permissions]{ width="400" }
|
||||
|
||||
You can also transfer your note ownership to another user, if you like.
|
||||
The owner of a note, is the only one who can change the permissions or delete the note.
|
||||
|
||||
You can add other users by entering their username into the field "Add user" and submit through the
|
||||
plus-icon button. If a username does not exist, you'll see an error notification appearing in the
|
||||
top right of the app.
|
||||
|
||||
There are two special kinds of permission that you can set below the individual user permissions.
|
||||
The entry "All logged-in users" refers - as the name says - to the group of registered user accounts
|
||||
on the instance. This becomes useful, if you have a known group of users on your instance and
|
||||
registration disabled.
|
||||
The other entry "Everyone" means that this permission is applied to everyone who accesses the note
|
||||
by its URL. This means the URL should be treated like a secret in case of (write) access.
|
||||
|
||||
|
||||
## Working with images
|
||||
|
||||
## Adding frontmatter metadata
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Checkout HedgeDoc's markdown syntax reference][hfm]
|
||||
- [Creating your first presentation][getting-started/first-presentation]
|
||||
- [Advanced configuration options][config]
|
||||
|
||||
[new-note]: ../images/tutorial/app-bar.png
|
||||
[editor]: ../images/tutorial/note/editor.png
|
||||
[editor-text]: ../images/tutorial/note/editor-text.png
|
||||
[collaboration]: ../images/tutorial/note/collaboration.png
|
||||
[permissions]: ../images/tutorial/note/permissions.png
|
||||
|
||||
[hfm]: ../references/hfm.md
|
||||
[getting-started/first-presentation]: first-presentation.md
|
||||
[config]: ../config/index.md
|
||||
5
docs/content/getting-started/first-presentation.md
Normal file
5
docs/content/getting-started/first-presentation.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Create your first presentation
|
||||
|
||||
TODO: This pages is still missing some content.
|
||||
See this issue for more information and if you want to contribute:
|
||||
<https://github.com/hedgedoc/hedgedoc/issues/4830>
|
||||
40
docs/content/getting-started/index.md
Normal file
40
docs/content/getting-started/index.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Getting started
|
||||
|
||||
These tutorials are detailed step-by-step instructions.
|
||||
Start here to learn how to create your first note or presentation, how to manage your
|
||||
notes or even how to setup your own instance.
|
||||
|
||||
<!-- markdownlint-disable no-inline-html -->
|
||||
<div class='topic-container'>
|
||||
<a href='/getting-started/setup/'>
|
||||
<div class='topic'>
|
||||
<span>🚀</span>
|
||||
<span>Install HedgeDoc</span>
|
||||
</div>
|
||||
</a>
|
||||
<a href='/getting-started/user/'>
|
||||
<div class='topic'>
|
||||
<span>🙎</span>
|
||||
<span>Create a user</span>
|
||||
</div>
|
||||
</a>
|
||||
<a href='/getting-started/first-note/'>
|
||||
<div class='topic'>
|
||||
<span>📝</span>
|
||||
<span>Create your first note</span>
|
||||
</div>
|
||||
</a>
|
||||
<a href='/getting-started/explore/'>
|
||||
<div class='topic'>
|
||||
<span>🔭</span>
|
||||
<span>Explore notes</span>
|
||||
</div>
|
||||
</a>
|
||||
<a href='/getting-started/first-presentation/'>
|
||||
<div class='topic'>
|
||||
<span>📽</span>
|
||||
<span>Create your first presentation</span>
|
||||
</div>
|
||||
</a>
|
||||
</div>
|
||||
<!-- markdownlint-enable no-inline-html -->
|
||||
135
docs/content/getting-started/setup.md
Normal file
135
docs/content/getting-started/setup.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# Install HedgeDoc
|
||||
|
||||
After completing this tutorial you'll have your own HedgeDoc instance running.
|
||||
We will use [Docker][docker-docs] to accomplish this.
|
||||
|
||||
!!! warning "HedgeDoc 2 is currently in alpha"
|
||||
Alpha releases come with no guarantees regarding upgradeability.
|
||||
It is very likely that you will need to wipe the database between alpha releases.
|
||||
Please set up a separate instance to test HedgeDoc 2, there is currently no migration path
|
||||
from HedgeDoc 1.
|
||||
|
||||
<!-- markdownlint-disable proper-names -->
|
||||
<!-- markdownlint-disable line-length -->
|
||||
|
||||
1. Open the terminal of the machine you want to install HedgeDoc on.
|
||||
|
||||
2. Check if you have Docker installed by running `docker --version`.
|
||||
The response should contain some version number greater than `20.10.13`.
|
||||
If you don't have Docker installed or if the version is too old, please refer to
|
||||
[the Docker install guide][docker-install] to install Docker.
|
||||
|
||||
3. Create a new directory for your HedgeDoc instance: `mkdir -p /opt/hedgedoc`.
|
||||
|
||||
4. Change into the directory with `cd /opt/hedgedoc`.
|
||||
|
||||
5. Download these files:
|
||||
- `curl -o .env https://raw.githubusercontent.com/hedgedoc/hedgedoc/refs/heads/develop/docker/.env`
|
||||
- `curl -o Caddyfile https://raw.githubusercontent.com/hedgedoc/hedgedoc/refs/heads/develop/docker/Caddyfile`
|
||||
- `curl -o docker-compose.yml https://raw.githubusercontent.com/hedgedoc/hedgedoc/refs/heads/develop/docker/docker-compose.yml`
|
||||
<!-- TODO: Create short links for these URLs, for example at source.hedgedoc.org/docker/Caddyfile etc. -->
|
||||
|
||||
6. Open the file `.env` in the editor of your choice (for example with `nano`) and edit the
|
||||
following variables:
|
||||
- `HD_BASE_URL`: This should contain the full url you intend to run HedgeDoc on (e.g. for the
|
||||
demo this would be `https://demo.hedgedoc.org`). If you just want to run HedgeDoc on your
|
||||
local machine for now `https://hedgedoc.localhost` should be sufficient for testing.
|
||||
- `HD_SESSION_SECRET`: This should contain a long and random secret for your login sessions.
|
||||
You can generate it with `pwgen -s 64 1` or any other way you see fit.
|
||||
If you don't have `pwgen` installed you can also use this command which should work
|
||||
out of the box: `tr -dc A-Za-z0-9 < /dev/urandom | head -c 64`
|
||||
- `HD_DATABASE_PASS`: This should contain a stronger password than `password` for your database.
|
||||
You can again use `pwgen -s 64 1` or a similar command to generate it.
|
||||
|
||||
7. Start the Docker containers by running `docker compose up -d`. This command will start four docker
|
||||
containers: The HedgeDoc frontend, the HedgeDoc backend, a PostgreSQL database and the Caddy reverse-proxy.
|
||||
|
||||
8. Navigate your browser to the url you chose in step 6. Your instance is now ready to use.
|
||||
|
||||
<!-- markdownlint-disable no-space-in-code -->
|
||||
|
||||
!!! info Using a different port
|
||||
This tutorial assumes that you run your HedgeDoc 2 instance on port 80 and 443 (HTTP and HTTPS).
|
||||
If you want to use a custom port, be sure to update your `.env` file to include the port in the
|
||||
`HD_BASE_URL` variable as well as update the port bindings in the `docker-compose.yml` file.
|
||||
For example, when using the base URL `http://192.168.1.100:8080`, only use the following ports
|
||||
section for the `proxy` service:
|
||||
```yaml
|
||||
ports:
|
||||
- "8080:8080"
|
||||
```
|
||||
|
||||
<!-- markdownlint-enable no-space-in-code -->
|
||||
<!-- markdownlint-enable line-length -->
|
||||
<!-- markdownlint-enable proper-names -->
|
||||
|
||||
You can now play around with your HedgeDoc instance and read about next steps
|
||||
as either [a new user](#for-users) or [an admin](#for-admins).
|
||||
|
||||
## Next Steps
|
||||
|
||||
### For Users
|
||||
|
||||
- [Creating a user account][getting-started/user]
|
||||
- [Creating your first note][getting-started/first-note]
|
||||
- [Explore notes][getting-started/explore]
|
||||
- [Creating your first presentation][getting-started/first-presentation]
|
||||
|
||||
### For admins
|
||||
|
||||
- [How to use a reverse proxy][reverse-proxying]
|
||||
- [How to back up HedgeDoc][backups]
|
||||
- [How to use other authentication methods][auth-methods]
|
||||
- [Advanced configuration options][config]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port already used
|
||||
|
||||
```text
|
||||
Error response from daemon: driver failed programming external connectivity: Bind for 0.0.0.0:80
|
||||
failed: port is already allocated.
|
||||
```
|
||||
|
||||
If you see this error, it means there is already something running on your machine that uses
|
||||
port `80` or `443`. The easiest fix for this is to stop the other application. You can use the
|
||||
command `ss -tulpn` to see which application utilizes which port.
|
||||
If you want to run multiple applications on that port on your server you may want to read our guide
|
||||
about [reverse proxying][reverse-proxying].
|
||||
|
||||
### Instance unreachable
|
||||
|
||||
You followed the guide to set up your instance, but when trying to access it in the browser, you
|
||||
receive an error like `ERR_CONNECTION_REFUSED`.
|
||||
|
||||
First, check that the Docker containers are running. For this you can use the command
|
||||
`docker compose ps -a`. If some of them are not running, check the logs and look out for error
|
||||
messages. You can use `docker compose logs` for this.
|
||||
|
||||
In case the containers are running but you still can't reach HedgeDoc in the browser, verify that
|
||||
the content of the variable `HD_BASE_URL` in the `.env` file matches exactly the URL you are trying
|
||||
to open. Verify that the ports (`80` or `443` or a custom one) are correctly mapped in the
|
||||
`docker-compose.yml`.
|
||||
|
||||
### Connection insecure
|
||||
|
||||
When accessing the HedgeDoc instance in your browser, you receive a warning that the HTTPS
|
||||
certificate is not trustworthy. This is the case, if you use a URL ending in `.localhost`.
|
||||
Caddy creates a temporary HTTPS certificate which is not signed by any public CA. You can
|
||||
safely ignore and bypass this error. See [the Caddy docs on HTTPS][caddy-https] for more
|
||||
information.
|
||||
|
||||
[docker-docs]: https://docs.docker.com/
|
||||
[docker-install]: https://docs.docker.com/engine/install/
|
||||
|
||||
[getting-started/user]: user.md
|
||||
[getting-started/first-note]: first-note.md
|
||||
[getting-started/first-presentation]: first-presentation.md
|
||||
[getting-started/explore]: explore.md
|
||||
|
||||
[reverse-proxying]: ../guides/reverse-proxy.md
|
||||
[backups]: ../guides/backup.md
|
||||
[auth-methods]: ../guides/auth.md
|
||||
|
||||
[config]: ../config/index.md
|
||||
[caddy-https]: https://caddyserver.com/docs/automatic-https
|
||||
50
docs/content/getting-started/user.md
Normal file
50
docs/content/getting-started/user.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Create an user account
|
||||
|
||||
This tutorial assumes that you just deployed a HedgeDoc instance with [this guide][setup].
|
||||
We'll assume the domain you use for the instance is <https://hedgedoc.localhost>, so please
|
||||
substitute it with your actual domain anywhere you encounter <https://hedgedoc.localhost> if
|
||||
that differs.
|
||||
|
||||
1. Go to <https://hedgedoc.localhost>. You will be greeted by the login page.
|
||||
|
||||
![HedgeDoc login page][login-page]{ width="700" }
|
||||
|
||||
2. Click on the "Register" button in "Sign in via Username" section.
|
||||
|
||||
3. Choose your preferred username, display name and password.
|
||||
|
||||
You are able to change any of these values except the username, so choose a username
|
||||
you want to keep. The username needs to be lowercase and may only contain the letters a-z,
|
||||
the numbers 0-9, and the underscore (_), dot (.) and hyphen (-).
|
||||
![Register form][register-form]{ width="400" }
|
||||
|
||||
4. Click on the "Register" button.
|
||||
|
||||
If everything worked, you'll now get redirected to the "explore page", which is the start
|
||||
page for accessing your notes. A notification in the top right confirms your account creation.
|
||||
|
||||
![Notification confirming the successful account creation][success-notification]{ width="400" }
|
||||
|
||||
HedgeDoc stores your login for 14 days in your browser per default. You can configure this
|
||||
session duration via the config options. Of course, you can always log out of your account
|
||||
to clear the session.
|
||||
|
||||
The next time you need to log in, just use your chosen username and password.
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Creating your first note][getting-started/first-note]
|
||||
- [Learn about the explore page][getting-started/explore]
|
||||
- [Creating your first presentation][getting-started/first-presentation]
|
||||
- [Advanced configuration options][config]
|
||||
|
||||
[setup]: ./setup.md
|
||||
|
||||
[login-page]: ../images/tutorial/user/login-page.png
|
||||
[register-form]: ../images/tutorial/user/register-form.png
|
||||
[success-notification]: ../images/tutorial/user/notification-success.png
|
||||
|
||||
[getting-started/first-note]: first-note.md
|
||||
[getting-started/first-presentation]: first-presentation.md
|
||||
[getting-started/explore]: explore.md
|
||||
[config]: ../config/index.md
|
||||
Loading…
Add table
Add a link
Reference in a new issue