docs/update outline (#471)

* docs update * reorganize * plausible analytics Co-authored-by: hay-kot <hay-kot@pm.me>
2025-10-30 09:43:43 -04:00 · 2021-06-07 15:04:30 -08:00
parent 95b6ab86d0
commit a75de6d1cf
29 changed files with 104 additions and 78 deletions
--- a/docs/docs/documentation/community-guide/.header.md
+++ b/docs/docs/documentation/community-guide/.header.md
@@ -0,0 +1,2 @@
+!!! info
+	This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
--- a/docs/docs/documentation/community-guide/bulk-url-import.md
+++ b/docs/docs/documentation/community-guide/bulk-url-import.md
@@ -0,0 +1,93 @@
+!!! info
+	This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
+
+
+Recipes can be imported in bulk from a file containing a list of URLs. This can be done using the following bash or python scripts with the `list` file containing one URL per line.
+
+#### Bash
+```bash
+#!/bin/bash
+
+function authentification () {
+  auth=$(curl -X 'POST' \
+    "$3/api/auth/token" \
+    -H 'accept: application/json' \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    -d 'grant_type=&username='$1'&password='$2'&scope=&client_id=&client_secret=')
+
+    echo $auth |  sed -e 's/.*token":"\(.*\)",.*/\1/'
+}
+
+function import_from_file () {
+  while IFS= read -r line
+  do
+    echo $line
+    curl -X 'POST' \
+      "$3/api/recipes/create-url" \
+      -H "Authorization: Bearer $2" \
+      -H 'accept: application/json' \
+      -H 'Content-Type: application/json' \
+      -d '{"url": "'$line'" }'
+    echo
+  done < "$1"
+}
+
+input="list"
+mail="changeme@email.com"
+password="MyPassword"
+mealie_url=http://localhost:9000
+
+
+token=$(authentification $mail $password $mealie_url)
+import_from_file $input $token $mealie_url
+
+```
+
+#### Python
+```python
+import requests
+import re
+
+def authentification(mail, password, mealie_url):
+  headers = {
+    'accept': 'application/json',
+    'Content-Type': 'application/x-www-form-urlencoded',
+  }
+  data = {
+    'grant_type': '',
+    'username': mail,
+    'password': password,
+    'scope': '',
+    'client_id': '',
+    'client_secret': ''
+  }
+  auth = requests.post(mealie_url + "/api/auth/token", headers=headers, data=data)
+  token = re.sub(r'.*token":"(.*)",.*', r'\1', auth.text)
+  return token
+
+def import_from_file(input_file, token, mealie_url):
+  with open(input_file) as fp:
+    for l in fp:
+      line = re.sub(r'(.*)\n', r'\1', l)
+      print(line)
+      headers = {
+        'Authorization': "Bearer " + token,
+        'accept': 'application/json',
+        'Content-Type': 'application/json'
+      }
+      data = {
+        'url': line
+      }
+      response = requests.post(mealie_url + "/api/recipes/create-url", headers=headers, json=data)
+      print(response.text)
+
+input_file="list"
+mail="changeme@email.com"
+password="MyPassword"
+mealie_url="http://localhost:9000"
+
+
+token = authentification(mail, password, mealie_url)
+import_from_file(input_file, token, mealie_url)
+```
+
--- a/docs/docs/documentation/community-guide/home-assistant.md
+++ b/docs/docs/documentation/community-guide/home-assistant.md
@@ -0,0 +1,34 @@
+!!! info
+	This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
+
+
+In a lot of ways, Home Assistant is why this project exists! Since it Mealie has a robust API it makes it a great fit for interacting with Home Assistant and pulling information into your dashboard.
+
+### Get Todays Meal in Lovelace
+Starting in v0.4.1 you are now able to use the uri `/api/meal-plans/today/image?group_name=Home` to directly access the image to todays meal. This makes it incredible easy to include the image into your Home Assistant Dashboard using the picture entity. 
+
+Here's an example where `sensor.mealie_todays_meal` is pulling in the meal-plan name and I'm using the url to get the image.
+
+![api-extras-gif](../../assets/img/home-assistant-card.png)
+
+```yaml
+type: picture-entity
+entity: sensor.mealie_todays_meal
+name: Dinner Tonight
+show_state: true
+show_name: true
+image: 'http://localhost:9000/api/meal-plans/today/image?group_name=Home'
+style:
+.: |
+    ha-card {
+    max-height: 300px !important;
+    overflow: hidden;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    }
+```
+
+
+!!! tip
+    Due to how Home Assistant works with images, I had to include the additional styling to get the images to not appear distorted. This includes and [additional installation](https://github.com/thomasloven/lovelace-card-mod) from HACS. 
--- a/docs/docs/documentation/community-guide/ios.md
+++ b/docs/docs/documentation/community-guide/ios.md
@@ -0,0 +1,40 @@
+# Using iOS Shortcuts with Mealie
+
+!!! info
+	This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
+
+
+![](../../assets/img/iphone-image.png){: align=right style="height:400px;width:400px"}
+
+
+User  [brasilikum](https://github.com/brasilikum) opened an issue on the main repo about how they had created an [iOS shortcut](https://github.com/hay-kot/mealie/issues/103) for interested users. This is a useful utility for iOS users who browse for recipes in their web browser from their devices.
+
+Don't know what an iOS shortcut is? Neither did I! Experienced iOS users may already be familiar with this utility but for the uninitiated, here is the official Apple explanation:
+
+
+> A shortcut is a quick way to get one or more tasks done with your apps. The Shortcuts app lets you create your own shortcuts with multiple steps. For example, build a “Surf Time” shortcut that grabs the surf report, gives an ETA to the beach, and launches your surf music playlist.
+
+
+Basically it is a visual scripting language that lets a user build an automation in a guided fashion. The automation can be [shared with anyone](https://www.icloud.com/shortcuts/6ae356d5fc644cfa8983a3c90f242fbb) but if it is a user creation, you'll have to jump through a few hoops to make an untrusted automation work on your device. In brasilikum's shortcut, you need to make changes for it to work. Recent updates to the project have changed some of the syntax and folder structure since its original creation.
+
+
+![screenshot](../../assets/img/ios-shortcut-image.jpg){: align=right style="height:500;width:400px"}
+
+
+
+!!! tip
+    You may need to change the url depending on which version you're using. Recipe is now plural and there is no trailing "/" at the end of the string.
+    
+    ```
+    api/recipe/create-url/
+    ```
+
+    to
+
+    ```
+    api/recipes/create-url
+    ```
+
+    
+
+Having made those changes, you should now be able to share a website to the shortcut and have mealie grab all the necessary information!
--- a/docs/docs/documentation/community-guide/swag.md
+++ b/docs/docs/documentation/community-guide/swag.md
@@ -0,0 +1,92 @@
+# Using SWAG as Reverse Proxy
+
+!!! info
+	This guide was submitted by a community member. Find something wrong? Submit a PR to get it fixed!
+
+
+
+To make the setup of a Reverse Proxy much easier, Linuxserver.io developed [SWAG](https://github.com/linuxserver/docker-swag)  
+SWAG - Secure Web Application Gateway (formerly known as letsencrypt, no relation to Let's Encrypt™) sets up an Nginx web server and reverse proxy with PHP support and a built-in certbot client that automates free SSL server certificate generation and renewal processes (Let's Encrypt and ZeroSSL). It also contains fail2ban for intrusion prevention.
+
+## Step 1: Get a domain
+
+The first step is to grab a dynamic DNS if you don't have your own subdomain already. You can get this from for example [DuckDNS](https://www.duckdns.org).
+
+## Step 2: Set-up SWAG
+
+Then you will need to set up SWAG, the variables of the docker-compose are explained on the Github page of [SWAG](https://github.com/linuxserver/docker-swag).
+This is an example of how to set it up using duckdns and docker-compose.
+
+!!! example "docker-compose.yml"
+```yaml
+version: "2.1"
+services:
+swag:
+image: ghcr.io/linuxserver/swag
+container_name: swag
+cap_add:
+- NET_ADMIN
+environment:
+- PUID=1000
+- PGID=1000
+- TZ=Europe/Brussels
+- URL=<mydomain.duckdns>
+- SUBDOMAINS=wildcard
+- VALIDATION=duckdns
+- CERTPROVIDER= #optional
+- DNSPLUGIN= #optional
+- DUCKDNSTOKEN=<duckdnstoken>
+- EMAIL=<e-mail> #optional
+- ONLY_SUBDOMAINS=false #optional
+- EXTRA_DOMAINS=<extradomains> #optional
+- STAGING=false #optional
+volumes:
+- /etc/config/swag:/config
+ports:
+- 443:443
+restart: unless-stopped
+
+```
+
+Don't forget to change the <code>mydomain.duckns</code> into your personal domain and the <code>duckdnstoken</code> into your token and remove the brackets.
+
+## Step 3: Change the config files
+
+Navigate to the config folder of SWAG and head to <code>proxy-confs</code>. If you used the example above, you should navigate to: <code>/etc/config/swag/nginx/proxy-confs/</code>.
+There are a lot of preconfigured files to use for different apps such as radarr,sonarr,overseerr,...
+
+To use the bundled configuration file, simply rename <code>mealie.subdomain.conf.sample</code> in the proxy-confs folder to <code>mealie.subdomain.conf</code>.
+Alternatively, you can create a new file <code>mealie.subdomain.conf</code> in proxy-confs with the following configuration:
+
+!!! example "mealie.subdomain.conf"
+```yaml
+    server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+
+    	server_name mealie.*;
+
+    	include /config/nginx/ssl.conf;
+
+    	client_max_body_size 0;
+
+    	location / {
+        	include /config/nginx/proxy.conf;
+        	include /config/nginx/resolver.conf;
+        	set $upstream_app mealie;
+        	set $upstream_port 80;
+        	set $upstream_proto http;
+        	proxy_pass $upstream_proto://$upstream_app:$upstream_port;
+    		}
+
+	}	
+```
+
+## Step 4: Port-forward port 443
+
+Since SWAG allows you to set up a secure connection, you will need to open port 443 on your router for encrypted traffic. This is way more secure than port 80 for http.
+
+## Step 5: Restart SWAG
+
+When you change anything in the config of Nginx, you will need to restart the container using <code>docker restart swag</code>.
+If everything went well, you can now access mealie on the subdomain you configured: mealie.mydomain.duckdns.org