Merge branch 'documentation-improvements' into 'develop'

Small documentation improvements

See merge request pleroma/pleroma!1001

README.md

@@ -8,7 +8,7 @@ Pleroma is a microblogging server software that can federate (= exchange message
 
 Pleroma is written in Elixir, high-performance and can run on small devices like a Raspberry Pi.
 
-For clients it supports both the [GNU Social API with Qvitter extensions](https://twitter-api.readthedocs.io/en/latest/index.html) and the [Mastodon client API](https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md).
+For clients it supports both the [GNU Social API with Qvitter extensions](https://twitter-api.readthedocs.io/en/latest/index.html) and the [Mastodon client API](https://docs.joinmastodon.org/api/guidelines/).
 
 - [Client Applications for Pleroma](https://docs-develop.pleroma.social/clients.html)
 

docs/admin/backup.md

@@ -1,4 +1,6 @@
-# Backup your instance
+# Backup/Restore your instance
+
+## Backup
 
 1. Stop the Pleroma service.
 2. Go to the working directory of Pleroma (default is `/opt/pleroma`)
@@ -6,7 +8,7 @@
 4. Copy `pleroma.pgdump`, `config/prod.secret.exs` and the `uploads` folder to your backup destination. If you have other modifications, copy those changes too.
 5. Restart the Pleroma service.
 
-## Restore your instance
+## Restore
 
 1. Stop the Pleroma service.
 2. Go to the working directory of Pleroma (default is `/opt/pleroma`)

docs/admin/updating.md

@@ -1,9 +1,9 @@
 # Updating your instance
-1. Stop the Pleroma service.
+1. Go to the working directory of Pleroma (default is `/opt/pleroma`)
-2. Go to the working directory of Pleroma (default is `/opt/pleroma`)
+2. Run `git pull`. This pulls the latest changes from upstream.
-3. Run `git pull`. This pulls the latest changes from upstream.
+3. Run `mix deps.get`. This pulls in any new dependencies.
-4. Run `mix deps.get`. This pulls in any new dependencies.
+4. Stop the Pleroma service.
 5. Run `mix ecto.migrate`[^1]. This task performs database migrations, if there were any.
-6. Restart the Pleroma service.
+6. Start the Pleroma service.
 
 [^1]: Prefix with `MIX_ENV=prod` to run it using the production config file.

docs/config.md

@@ -193,6 +193,44 @@ This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:i
 * `port`: Port to bind to
 * `dstport`: Port advertised in urls (optional, defaults to `port`)
 
+## Pleroma.Web.Endpoint
+`Phoenix` endpoint configuration, all configuration options can be viewed [here](https://hexdocs.pm/phoenix/Phoenix.Endpoint.html#module-dynamic-configuration), only common options are listed here
+* `http` - a list containing http protocol configuration, all configuration options can be viewed [here](https://hexdocs.pm/plug_cowboy/Plug.Cowboy.html#module-options), only common options are listed here
+  - `ip` - a tuple consisting of 4 integers
+  - `port`
+* `url` - a list containing the configuration for generating urls, accepts
+  - `host` - the host without the scheme and a post (e.g `example.com`, not `https://example.com:2020`)
+  - `scheme` - e.g `http`, `https` 
+  - `port`
+  - `path`
+
+
+**Important note**: if you modify anything inside these lists, default `config.exs` values will be overwritten, which may result in breakage, to make sure this does not happen please copy the default value for the list from `config.exs` and modify/add only what you need
+
+Example: 
+```elixir
+config :pleroma, Pleroma.Web.Endpoint,
+  url: [host: "example.com", port: 2020, scheme: "https"],
+  http: [
+    # start copied from config.exs
+    dispatch: [
+      {:_,
+       [
+         {"/api/v1/streaming", Pleroma.Web.MastodonAPI.WebsocketHandler, []},
+         {"/websocket", Phoenix.Endpoint.CowboyWebSocket,
+          {Phoenix.Transports.WebSocket,
+           {Pleroma.Web.Endpoint, Pleroma.Web.UserSocket, websocket_config}}},
+         {:_, Phoenix.Endpoint.Cowboy2Handler, {Pleroma.Web.Endpoint, []}}
+       ]}
+    # end copied from config.exs
+    ],
+    port: 8080,
+    ip: {127, 0, 0, 1}
+  ]
+```
+
+This will make Pleroma listen on `127.0.0.1` port `8080` and generate urls starting with `https://example.com:2020`
+
 ## :activitypub
 * ``accept_blocks``: Whether to accept incoming block activities from other instances
 * ``unfollow_blocked``: Whether blocks result in people getting unfollowed

docs/config/howto_change_ip_and_port.md

@@ -1,7 +0,0 @@
-# How to change the port or IP Pleroma listens to
-To change the port or IP Pleroma listens to, head over to your generated config inside the Pleroma folder at config/prod.secret.exs and edit the following according to your needs.
-```
-config :pleroma, Pleroma.Web.Endpoint,
-   [...]
-   http: [ip: {127, 0, 0, 1}, port: 4000]
-```

docs/introduction.md

@@ -1,11 +1,11 @@
 # Introduction to Pleroma
-**What is Pleroma?**  
+## What is Pleroma?
 Pleroma is a federated social networking platform, compatible with GNU social, Mastodon and other OStatus and ActivityPub implementations. It is free software licensed under the AGPLv3.  
 It actually consists of two components: a backend, named simply Pleroma, and a user-facing frontend, named Pleroma-FE. It also includes the Mastodon frontend, if that's your thing.  
 It's part of what we call the fediverse, a federated network of instances which speak common protocols and can communicate with each other.  
 One account on a instance is enough to talk to the entire fediverse!
   
-**How can I use it?**
+## How can I use it?
 
 Pleroma instances are already widely deployed, a list can be found here:  
 http://distsn.org/pleroma-instances.html
@@ -14,14 +14,14 @@ If you don't feel like joining an existing instance, but instead prefer to deplo
 Installation instructions can be found here:  
 [main Pleroma wiki](/)
   
-**I got an account, now what?**  
+## I got an account, now what?
 Great! Now you can explore the fediverse!  
 - Open the login page for your Pleroma instance (for ex. https://pleroma.soykaf.com) and login with your username and password.  
 (If you don't have one yet, click on Register) :slightly_smiling_face:  
 
 At this point you will have two columns in front of you.
 
-***left column***
+### Left column
 - first block: here you can see your avatar, your nickname a bio, and statistics (Statuses, Following, Followers).  
 Under that you have a text form which allows you to post new statuses. The icon on the left is for uploading media files and attach them to your post. The number under the text form is a character counter, every instance can have a different character limit (the default is 5000).  
 If you want to mention someone, type @ + name of the person. A drop-down menu will help you in finding the right person. :slight_smile:   
@@ -37,7 +37,7 @@ To post your status, simply press Submit.
 
 - fourth block: This is the Notifications block, here you will get notified whenever somebody mentions you, follows you, repeats or favorites one of your statuses.
 
-***right column***  
+### Right column
 This is where the interesting stuff happens! :slight_smile:   
 Depending on the timeline you will see different statuses, but each status has a standard structure:
 - Icon + name + link to profile. An optional left-arrow if it's a reply to another status (hovering will reveal the replied-to status).
@@ -46,7 +46,7 @@ Depending on the timeline you will see different statuses, but each status has a
 - The text of the status, including mentions. If you click on a mention, it will automatically open the profile page of that person.
 - Four buttons (left to right): Reply, Repeat, Favorite, Delete.
 
-**Mastodon interface**
+## Mastodon interface
 If the Pleroma interface isn't your thing, or you're just trying something new but you want to keep using the familiar Mastodon interface, we got that too! :smile:  
 Just add a "/web" after your instance url (for ex. https://pleroma.soycaf.com/web) and you'll end on the Mastodon web interface, but with a Pleroma backend! MAGIC! :fireworks:  
 For more information on the Mastodon interface, please look here: