Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft: Port to Docusaurus #2568

Open
wants to merge 46 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
02ffaa0
Add docusaurus configuration ; move grav configuration to __grav
Salamandar Mar 12, 2025
46c9829
Rename images as static/img
Salamandar Mar 12, 2025
5bd8593
Swizzle the NotFound page
Salamandar Mar 13, 2025
d1f6806
Bump deps
Salamandar Mar 13, 2025
0d2daf8
cleanup theme code
Salamandar Mar 13, 2025
8ab2bfd
docusaurus: Convert 00.home/docs.md
Salamandar Mar 13, 2025
0fceb96
docusaurus: Convert 01.overview
Salamandar Mar 13, 2025
a67a170
docusaurus: Convert 02.overview/index
Salamandar Mar 13, 2025
91b11dc
docusaurus: Convert 02.administer/05,15.admin_guide
Salamandar Mar 13, 2025
e12fa0f
docusaurus: Convert 02.administer/20.backups
Salamandar Mar 13, 2025
f17d4b7
docusaurus: Convert 02.administer/45.tutorials
Salamandar Mar 13, 2025
f702e70
docusaurus: Convert 02.administer/50.troubleshooting
Salamandar Mar 13, 2025
d68de22
Rename indexes as index.mdx for readability
Salamandar Mar 13, 2025
3b76862
docusaurus: Convert 02.administer/55.providers
Salamandar Mar 13, 2025
6086bd0
docusaurus: Convert 03.user_guide
Salamandar Mar 13, 2025
792be43
Update overview pages
Salamandar Mar 13, 2025
d9d8406
Update administer page
Salamandar Mar 13, 2025
88ab6e3
Update docusaurus panels
Salamandar Mar 13, 2025
02b941e
sidebar: Add link to applications and forum
Salamandar Mar 13, 2025
0a347a3
docusaurus: Convert 05.community
Salamandar Mar 13, 2025
a7894ab
docusaurus: Convert 06.contribute/05.write_documentation
Salamandar Mar 14, 2025
97683fd
docusaurus: Convert 06.contribute/10.packaging_apps
Salamandar Mar 14, 2025
ac26538
docusaurus: Convert 06.contribute/15.dev
Salamandar Mar 14, 2025
4c91237
Miscelaneous docs fixes, tips notes and images
Salamandar Mar 14, 2025
c0a6ead
Add columns and react-player
Salamandar Mar 14, 2025
f5dac64
Renumerote administer and user_guide to add 02.install in the near fu…
Salamandar Mar 14, 2025
6a81edd
Start the install category
Salamandar Mar 14, 2025
7dec46a
Merge branch 'master' into docusaurus
Salamandar Mar 14, 2025
925da7f
Update doc generator scripts for docusaurus
Salamandar Mar 14, 2025
c915f20
Regenerate doc from sources
Salamandar Mar 14, 2025
a9e9576
Fix resources doc template
Salamandar Mar 14, 2025
a39e846
Resources: reduce the heading level of the TOC
Salamandar Mar 14, 2025
71cfc29
docusaurus: port install/post_install, install/providers
Salamandar Mar 14, 2025
7e33e14
Misc fixes
Salamandar Mar 14, 2025
8e15e68
move install on top of debian
Salamandar Mar 14, 2025
781c1f3
Add the post-install page
Salamandar Mar 14, 2025
be5243f
Add components for automatic images list
Salamandar Mar 15, 2025
32b3945
docusaurus: port install/
Salamandar Mar 15, 2025
c64b97e
Merge branch 'master' into docusaurus
Salamandar Mar 15, 2025
0bb605e
docusaurus: use client side module for images list
Salamandar Mar 15, 2025
c1f7b84
Remove demo HomepageFeatures
Salamandar Mar 15, 2025
6c91c67
Rename src/theme js as jsx
Salamandar Mar 15, 2025
6c709a3
Fix pages linting
Salamandar Mar 15, 2025
d23816b
fix broken links
Thovi98 Mar 14, 2025
711e656
continue fixing broken internal links
Salamandar Mar 15, 2025
b9f04df
continue fixing broken internal links
Salamandar Mar 15, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
34 changes: 24 additions & 10 deletions .gitignore
100755 → 100644
Original file line number Diff line number Diff line change
@@ -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
3 changes: 0 additions & 3 deletions .gitmodules

This file was deleted.

89 changes: 0 additions & 89 deletions Dockerfile

This file was deleted.

54 changes: 42 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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).
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
3 changes: 3 additions & 0 deletions babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
18 changes: 0 additions & 18 deletions docker-compose.yml

This file was deleted.

Original file line number Diff line number Diff line change
@@ -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.

Expand Down
59 changes: 59 additions & 0 deletions docs/01.overview/10.what_is_yunohost.mdx
Original file line number Diff line number Diff line change
@@ -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"}}/>
42 changes: 42 additions & 0 deletions docs/01.overview/15.try_yunohost.mdx
Original file line number Diff line number Diff line change
@@ -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"}}/>**
:::
5 changes: 5 additions & 0 deletions docs/01.overview/_category_.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
position: 1
label: Overview
link:
type: generated-index
title: Overview
16 changes: 16 additions & 0 deletions docs/02.install/10.providers/05.registrar/gandi.mdx
Original file line number Diff line number Diff line change
@@ -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)
19 changes: 19 additions & 0 deletions docs/02.install/10.providers/05.registrar/index.mdx
Original file line number Diff line number Diff line change
@@ -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) |
Loading
Loading