From dcf87984efb9229139ecee79bdd809680207babe Mon Sep 17 00:00:00 2001 From: DerLinkman Date: Fri, 13 Jan 2023 18:27:49 +0100 Subject: [PATCH] Updated README.md --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 6ae680971..8a919c0c3 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,17 @@ -# mailcow-docs-2.0 | [![pages-build-deployment](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/pages/pages-build-deployment) -The rework of the official mailcow docs +# mailcow-docs | [![pages-build-deployment](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/pages/pages-build-deployment) +The official mailcow docs based on mkdocs-material -### Introduction: -The new 2.0 version of the mailcow documentation has been redesigned from scratch based on the original. +## Introduction: +--- +The mailcow documentation has been redesigned from scratch based on the original (legacy-1.0 branch). -Advantages compared to the 1.0 version: +Advantages compared to the legacy version: - Full translation support (English and German are officially supported by Servercow/tinc). - New folder structure for better overview/ordering of sub-pages. +- Switches for Command Syntax (Docker Compose especially) -Due to the fact that this version now has some serious changes compared to the 1.0 version, all pending merge requests are no longer compatible with this version. +## Contributions: --- ### About contributions: @@ -20,15 +22,35 @@ Of course, we will also make our contributions to the documentation, but especia To contribute new pages/translations simply clone the repository and then work with your cloned repository. Once you are done with your work start a pull request, if approved this will then be implemented into the actual documentation. ---- -### How to add new translations: +### Use the Compose Switch in a new/edited Page: +If you plan to contribute to our docs please make sure to always specify **both** docker compose syntaxes! This can be done by using a "switch". Example: + +``` +=== "docker compose (Plugin)" + + ``` bash + docker compose exec rspamd-mailcow bash + ``` + +=== "docker-compose (Standalone)" + + ``` bash + docker-compose exec rspamd-mailcow bash + ``` +``` + +Simply change the Content of this two cases acording to your desired needs. + + +### Translations +#### About Translations: So you want to provide a new translation for the documentation? Great, thanks for that <3 There are a few things to keep in mind, which are essential for a smooth process: -##### Add the new Language to the Language selector: +#### Add the new Language to the Language selector: As a start for possible translations, the language must first be added to the language selection. To add it, edit the mkdocs.yml file and add the language in the "translations" section (under the already existing languages): ``` [...] @@ -51,7 +73,7 @@ If a page does **NOT** exist in a language, the English version of the page will Images can also be "translated"! These are distinguished (similar to the pages) by the country codes. -##### Translate the menu: +#### Translate the menu: The menu is **NOT** translated by default and must be translated by hand, this is also done in the mkdocs.yml: ``` [...] @@ -72,7 +94,6 @@ The menu is **NOT** translated by default and must be translated by hand, this i ``` The preceding English variant **MUST be kept**, otherwise the translation will **not work**. ---- ### Folder structure: ``` @@ -113,10 +134,9 @@ docs <-- Root Folder │   ├── file.XX.md ``` +## Testing --- -### Testing - To build and test it locally, you need the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), [MkDocs](https://www.mkdocs.org/) itself and [Pygments](http://pygments.org/). To install these with [pip](https://pip.pypa.io/en/stable/) and get it up and running, fire up your terminal and enter ``` @@ -133,4 +153,13 @@ If you want to test how the documentation looks like with the placeholder values For Example: ``` http://127.0.0.1:8000/client/client-manual/#host=mail.test.org&email=mail@example.org&name=mail&ui=mail.example.org&port=443 -``` \ No newline at end of file +``` + +## Misc +--- + +mailcow is a registered word mark of The Infrastructure Company GmbH, Parkstr. 42, 47877 Willich, Germany. + +The project is managed and maintained by The Infrastructure Company GmbH. + +Originated from @andryyy (André)