Draft: Port to Docusaurus

.gitignore

@@ -1,10 +1,24 @@
-/*
-!.github
-!/pages
-!/images
-!/themes
-!/Dockerfile
-!/docker-compose.yml
-!/dev/plugins
-!/markdownlint-rules-grav-pages
-!/scripts
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Virtualenv for tools
+/.venv
+/venv

README.md

@@ -1,33 +1,59 @@
 # YunoHost Documentation
 
-- [Web Site](https://yunohost.org)
-- Based on [Grav](https://getgrav.org/)
+This repository contains the code for [the YunoHost documentation](https://doc.yunohost.org).
 
-Please report [issues on YunoHost bugtracker](https://github.com/YunoHost/issues/issues).
+It is built using [Docusaurus 2](https://docusaurus.io), a modern static website generator.
 
-## Note on package documentation
+Please report issues on [the YunoHost bugtracker](https://github.com/YunoHost/issues/issues).
 
-Package documentation should be done in the package repository itself, under the `/doc` folder.  
-You can learn about it here: <https://yunohost.org/packaging_app_doc>
+> [!WARNING]  
+> Package documentation should be done in the package repository itself, under the `/doc` folder.  
+> You can learn about it here: <https://doc.yunohost.org/packaging_app_doc>
 
-## Contributing
+## Usage
+
+### Installation
+
+```bash
+$ yarn
+```
+
+### Local Development
+
+```bash
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-This repo use a **submodule** to provide the theme. So when you clone use:
+### Build
 
 ```bash
-git clone --recursive https://github.com/YunoHost/doc.git
+$ yarn build
 ```
 
-You can refer to the page on [writing documentation](https://yunohost.org/write_documentation).
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-If you know docker, you can run:
+### Deployment
+
+Using SSH:
+
+```bash
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
 
 ```bash
-docker-compose up
+$ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
 ### Regenerate the CSS
 
+FIXME: not relevant for docusaurus? But it can use scss
+
 We use scss to manage the CSS. If you want to change it, you must rebuild it.
 
 First install npm, then in the root folder of this repo, install sass: `npm install sass`
@@ -40,3 +66,7 @@ Finally you can rebuild the CSS with (You can replace `expanded` by `compressed`
 
 Source:
 <https://sass-lang.com/guide>
+
+## Contributing
+
+You can refer to the page on [writing documentation](https://doc.yunohost.org/write_documentation).

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

pages/01.overview/05.self_hosting/self_hosting.md → docs/01.overview/05.self_hosting.md

@@ -1,17 +1,13 @@
 ---
 title: Self-hosting
-template: docs
-taxonomy:
-    category: docs
-routes:
-  default: '/selfhosting'
+description: What is self-hosting?
 ---
 
 Self-hosting is the activity of owning and administrating your own server, typically at home, to host **your personal data and services** yourself instead of relying exclusively on third-parties. For instance, you can self-host your blog, such that it 'lives' on a machine that you have control of, instead of having it on somebody else's computer (a.k.a. FAANGS or The Cloud) in exchange for money, advertisement or private data.
 
 Self-hosting implies owning a server. **A server is a computer which is typically accessible on the network 24/7**, and usually does not have any screen or keyboard (it is instead controlled remotely). Contrarily to a popular belief, a server is not necessarily a huge and extra-powerful machine: nowadays, a small, ~$30 ARM board is adequate for self-hosting.
 
-![](image://internet_topologies.png)
+![Internet topologies diagram](/img/internet_topologies.png)
 
 Self-hosting is not about making "your Internet" more secure and does not provide anonymity by itself. Instead, it is about being autonomous, and in control of your services and data - which also means being responsible for them.
 

docs/01.overview/10.what_is_yunohost.mdx

@@ -0,0 +1,59 @@
+---
+title: What is YunoHost?
+description: " "
+---
+
+<img src={require('/img/YunoHost_logo_vertical.png').default} alt="YunoHost logo" id="ynhlogo" style={{display: "block", textAlign: "center", margin: "auto"}}/>
+
+YunoHost is an **operating system** aiming to simplify **server administration** and therefore democratize [self-hosting](/overview/self_hosting) while making sure it stays reliable, secure, ethical and lightweight. It is a copylefted libre software project maintained exclusively by volunteers. Technically, it can be seen as a distribution based on [Debian GNU/Linux](https://debian.org) and can be installed on [many kinds of hardware](/install).
+
+## Features
+
+import useBaseUrl from '@docusaurus/useBaseUrl'
+export function SmallInline({url, alt}) {
+  return (<img src={useBaseUrl(url)} width="32" style={{verticalAlign: "middle", margin: "5px"}} alt={alt}/>);
+}
+
+- &#8203;<SmallInline url='/img/icon-debian.png' alt="debian logo"/> Based on Debian, for a trustworthy & familiar base;
+- &#8203;<SmallInline url='/img/icon-tools.png' alt="tools logo"/> Administer your server through a **friendly web interface** as well as a handy CLI;
+- &#8203;<SmallInline url='/img/icon-package.png' alt="package logo"/> Deploy **apps in just a few clicks** from [our more than 500 apps catalog](https://apps.yunohost.org)!;
+- &#8203;<SmallInline url='/img/icon-users.png' alt="users logo"/> Manage **users** <small>(based on LDAP)</small>;
+- &#8203;<SmallInline url='/img/icon-globe.png' alt="globe logo"/> Manage **domain names**;
+- &#8203;<SmallInline url='/img/icon-medic.png' alt="medic logo"/> Create and restore **backups**;
+- &#8203;<SmallInline url='/img/icon-door.png' alt="door logo"/> Connect to all apps simultaneously through the **user portal** <small>(NGINX, SSOwat)</small>;
+- &#8203;<SmallInline url='/img/icon-mail.png' alt="mail logo"/> Includes a **full e-mail stack** <small>(Postfix, Dovecot, Rspamd, DKIM)</small>;
+- &#8203;<SmallInline url='/img/icon-messaging.png' alt="messaging logo"/>... as well as **an instant messaging server** <small>(XMPP)</small>
+- &#8203;<SmallInline url='/img/icon-lock.png' alt="lock logo"/> Manages **SSL certificates** <small>(based on Let's Encrypt)</small>;
+- &#8203;<SmallInline url='/img/icon-shield.png' alt="shield logo"/>... and **security systems** <small>(`fail2ban`, `yunohost-firewall`)</small>.
+
+## Origin
+
+YunoHost was created in February 2012 after something like this:
+
+> "Shit, I'm too lazy to reconfigure my mail server... Beudbeud, how were you able to get your little server running with LDAP?"
+> <small>*Kload, February 2012*</small>
+
+All that was needed was an admin interface for Beudbeud's server to make something usable, so Kload decided to develop one. Finally, after automating several configs and packaging in some web apps, YunoHost v1 was finished.
+
+Noting the growing enthusiasm around YunoHost and around self-hosting in general, the original developers along with new contributors decided to start work on version 2, a more extensible, more powerful, more easy-to-use, and at that, one that makes a nice cup of fair-trade coffee for the elves of Lapland.
+
+The name **YunoHost** comes from the jargon "[Y U NO](https://knowyourmeme.com/memes/y-u-no-guy) Host". The [Internet meme](https://en.wikipedia.org/wiki/Internet_meme) should illustrate it:
+
+<center>
+![The meme in question, showing a guy with a face bent in frustration and questioning "Y U NO Host"](/img/dude_yunohost.jpg)
+</center>
+
+## What YunoHost is not?
+
+Even if YunoHost can handle multiple domains and multiple users, it is **not meant to be a mutualized system**.
+
+First, the software is too young, not tested at scale and thus probably not optimized well enough for hundreds of users at the same time. With that said, we do not want to lead the software in that direction. Virtualization democratizes, and its usage is recommended since it is a more watertight way to achieve mutualization than a "full-stack" system like YunoHost.
+
+You can host your friends, your family and your company safely and with ease, but you must **trust your users**, and they must trust you above all. If you want to provide YunoHost services for unknown persons anyway, a full VPS per user will be just fine, and we believe a better way to go.
+
+## Artworks
+
+Black and white YunoHost PNG logo by ToZz (400 × 400 px). Licence: CC-BY-SA 4.0. Logos and other artwork are available in [the Artworks repository](https://github.com/YunoHost/yunohost-artwork).
+
+<img src={require('/img/ynh_logo_black_300dpi.png').default} width="220" id="darklogo" style={{padding: "1rem"}}/>
+<img src={require('/img/ynh_logo_white_300dpi.png').default} width="220" id="whitelogo" style={{padding: "1rem"}}/>

docs/01.overview/15.try_yunohost.mdx

@@ -0,0 +1,42 @@
+---
+title: Try YunoHost
+description: A demo server
+routes:
+  default: '/try'
+---
+
+import YunoHostDocsCard from '@site/src/components/YunoHostDocsCard';
+import YunoHostDocsCardHeading from '@site/src/components/YunoHostDocsCard/YunoHostDocsCardHeading';
+
+# Try YunoHost on a demo server
+
+:::caution
+This demo server could be down from time to time, but at least you can test and that's really cool :)
+:::
+
+<div style={{display: "flex"}} >
+<YunoHostDocsCard>
+  <YunoHostDocsCardHeading url="https://demo.yunohost.org/?target=_blank&classes=btn,btn-lg,btn-success" color="#30ae40"> {
+  } <FAIcon icon='fa-user'/> User interface {
+  } </YunoHostDocsCardHeading>
+
+  username: `demo`
+
+  password: `demo`
+</YunoHostDocsCard>
+
+<YunoHostDocsCard>
+  <YunoHostDocsCardHeading url="https://demo.yunohost.org/yunohost/admin/?target=_blank&classes=btn,btn-lg,btn-primary" color="#1267da"> {
+  } <FAIcon icon='fa-cog'/> Administration interface {
+  } </YunoHostDocsCardHeading>
+
+  username: `demo`
+
+  password: `demo`
+
+</YunoHostDocsCard>
+</div>
+
+:::info
+**Demo server gracefully provided by [Gitoyen](https://www.gitoyen.net?target=_blank) <FAIcon icon="fa-heart" style={{color: "green"}}/>**
+:::

docs/01.overview/_category_.yaml

@@ -0,0 +1,5 @@
+position: 1
+label: Overview
+link:
+  type: generated-index
+  title: Overview

docs/02.install/10.providers/05.registrar/gandi.mdx

@@ -0,0 +1,16 @@
+---
+sidebar_label: Gandi
+title: Obtaining an API key from Gandi
+---
+
+This page is meant to guide you in obtaining an API key from Gandi in order to configure YunoHost's automatic DNS configuration mecanism
+
+:::caution
+**DO NOT share your API tokens with anybody!** A malicious attacker obtaining your tokens could take over your domain, and possibly your server!
+:::
+
+1. Go to [https://account.gandi.net/](https://account.gandi.net/)
+2. You should land on this page. Then click on 'Security'
+  ![](/img/registrar_api_gandi_1.png)
+3. In the next page, click on '(re)Generate the API key'.
+  ![](/img/registrar_api_gandi_2.png)

docs/02.install/10.providers/05.registrar/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Registrars
+link:
+  description: The guys that provide the domain name
+---
+
+Since version 4.3, YunoHost includes a mechanism to interface your server with your DNS registrar API, with the purpose of simplifying and automatizing DNS records registration and maintenance.
+
+The procedure requires an initial configuration where you need to generate an API key on your registrar's interface.
+
+Not all registrars are supported. So far, the community tested and validated the interface with [Gandi](https://gandi.net) and [OVH](https://ovh.com), which are recommended. The interface with other registrars may work, but is still considered experimental until we gather feedback from the community.
+
+The list below can help you to choose a registrar if you plan to buy a domain name to use it with YunoHost.
+
+| Registrar                           | Compatibility               | Easy to obtain an API key | Howto |
+|-------------------------------------|-----------------------------|---------------------------|-------|
+| [Gandi](https://www.gandi.net)      | ✘ (broken)                  | ✘   | [Obtain an API key](/install/providers/registrar/gandi) <br/> [See bug here](https://github.com/YunoHost/issues/issues/2419) |
+| [OVH](https://ovh.com/domaines)     | ✔ (tested)                  | ✘   | [Obtain an API key](/install/providers/registrar/ovh/autodns) <br/> [Configure manually](/install/providers/registrar/ovh/manualdns) |
+| [Namecheap](https://namecheap.com)  | ✘ (in lexicon but untested) | ✘✘✘ API not available without 50$ on the account | [Obtain an API key](/install/providers/registrar/namecheap) |