fix: update README

Author: c12simple

README.md

@@ -1,2 +1,125 @@
-# docs
-All Pydio Documentation
+# Pydio Docs Repository Structure
+The Pydio documentation repository is organized into multiple branches and components for managing and building documentation.
+
+# Main Branch
+The main branch contains the MkDocs configuration, tools, and utilities to convert and aggregate documents.
+
+## MkDocs Materials
+* overrides/
+* resources/
+* mkdocs.yml
+* requirements.txt
+* resources/versions.json: We use Mike to deploy multiple versions of the docs.
+Mike generates versions.json automatically; however, we maintain resources/versions.json to manually control versions and their labels.
+
+This file overrides the Mike-generated versions.json.
+
+## Document Conversion Tools
+Located under the tools/ directory, these scripts handle the migration and aggregation of legacy documents from multiple repositories into a unified structure.
+
+### git_script.sh
+
+#### Prerequisites
+Before running the script, clone the legacy repositories locally to:
+
+```
+LOCAL_REPO_ADMIN_GUIDE="/home/pydio/go/src/github.com/pydio/pydio-doc-admin-guide"
+LOCAL_REPO_DEVELOPER_GUIDE="/home/pydio/go/src/github.com/pydio/pydio-doc-developer-guide"
+LOCAL_REPO_KB="/home/pydio/go/src/github.com/pydio/pydio-doc-howto"
+```
+
+#### Functionality
+`git_script.sh` scans these repositories across their respective branches and performs:
+
+* Adds .nav.yaml files to each folder, containing frontmatter (slug, title, etc.).
+* Inserts frontmatter metadata into each .md file:
+* title, slug, weight (used to order pages).
+* Fixes image links within .md files.
+* Replaces [:summary] placeholders with actual section TOCs.
+
+
+### local-build.sh
+This script is used for local builds of the documentation using MkDocs and Mike.
+
+#### Mkdocs plugins build/setup
+
+Setup a clean python env
+
+```
+python -m venv /home/pydio/.venv
+```
+
+Propagate python Envs
+
+```
+source /home/pydio/.venv/bin/activate
+```
+
+pip install mkdocs mike
+pip install mkdocs-material mkdocs-redirects mkdocs-minify-plugin pymdown-extensions mkdocs-glightbox
+
+Install specific mkdocs plugin
+
+```
+pip install git+https://github.com/pydio/mkdocs-awesome-nav
+```
+
+`pydio/mkdocs-awesome-nav` is an specific plugin enabling following features:
+- Understand the frontmatter of .md files such as title, slug, weight
+- Understand the .nav.yaml of each section for menu & navigation bar
+
+For example:
+
+**Frontmatter:**
+
+```
+---
+slug: install-static-binaries
+title: Install Static Binaries
+description: Installing Pydio Cells on your server using our pre-compiled binaries.
+menu: Static Binaries
+language: und
+weight: 1
+menu_name: menu-admin-guide-v7-enterprise
+
+---
+Page content
+
+```
+
+**.nav.yaml:**
+
+```
+title: Quick Start
+abstract: This section provides a full-spectrum overview of Pydio Cells installation, configuration and usage.
+menu: Quick Start
+language: und
+weight: 1
+menu_name: menu-admin-guide-v7-enterprise
+
+slug: quick-start
+```
+
+## Document Branches
+The actual documentation contents are stored in version-specific branches:
+
+* cells-v5
+
+* cells-v4 (latest)
+
+* pydio-v8
+
+Each branch contains its own GitHub workflow file:
+
+`.github/workflows/build-docs.yml` — triggers the documentation rebuild on push events.
+
+
+## Artifact Branch
+
+* gh-pages
+
+GitHub Actions use MkDocs and Mike to build the documentation and store the resulting artifacts in this branch.
+
+A separate GitHub Pages workflow listens to changes on gh-pages and triggers the website update process.
+
+Live Documentation: https://pydio.github.io/docs