docs: migrate to MkDocs for site generation (#5227)

.dockerignore

@@ -1,3 +1,8 @@
-*
+.venv
-!docker/*
+dist
-!filebrowser
+.idea
+frontend/node_modules
+frontend/dist
+filebrowser.db
+site/docs/index.md
+site/docs/quickstart.md

.github/workflows/site-pr.yml

@@ -0,0 +1,22 @@
+name: Build Site Image
+
+on:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Build
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: ./Dockerfile.site
+          push: false
+

.github/workflows/site-publish.yml

@@ -0,0 +1,39 @@
+name: Build and Push Site Image
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: ./Dockerfile.site
+          push: true
+          tags: |
+            filebrowser/site:latest
+            ghcr.io/filebrowser/site:latest

.gitignore

@@ -6,6 +6,7 @@ rice-box.go
 /filebrowser
 /filebrowser.exe
 /dist
+.venv
 
 .DS_Store
 node_modules
@@ -41,3 +42,4 @@ build/
 
 default.nix
 Dockerfile.dev
+site/public/

Dockerfile.site

@@ -0,0 +1,22 @@
+FROM  squidfunk/mkdocs-material as build
+
+WORKDIR /build
+COPY site/requirements.txt /build/requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+COPY LICENSE /build/docs/LICENSE
+
+COPY site/ /build/
+
+COPY README.md /build/docs/index.md
+RUN sed -i 's|site/docs/||g' /build/docs/index.md
+
+RUN mkdocs build
+
+
+FROM ghcr.io/umputun/reproxy
+# enables automatic changelog generation by tools like Dependabot
+LABEL org.opencontainers.image.source="https://github.com/filebrowser/filebrowser"
+COPY --from=build /build/site /srv/site
+EXPOSE 8080
+USER app
+ENTRYPOINT ["/srv/reproxy", "--assets.location=/srv/site", "--assets.cache=30d", "--assets.cache=text/html:30s"]

Dockerfile.site.dev

@@ -0,0 +1,19 @@
+FROM squidfunk/mkdocs-material
+
+# Install inotify-tools for watching file changes
+RUN apk add --no-cache inotify-tools
+
+WORKDIR /build
+
+COPY site/requirements.txt /build/requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Expose the port for mkdocs serve
+EXPOSE 8000
+
+# Copy the watch script and make it executable
+COPY scripts/watch.sh /usr/local/bin/watch.sh
+RUN chmod +x /usr/local/bin/watch.sh
+
+# The entrypoint will run the initial setup and then start the server.
+ENTRYPOINT ["/usr/local/bin/watch.sh"]

Makefile

@@ -53,6 +53,21 @@ clean: clean-tools ## Clean
 bump-version: $(standard-version) ## Bump app version
 	$Q ./scripts/bump_version.sh
 
+.PHONY: site
+site: ## Build site
+	@rm -f  site/public/*
+	@docker rm -f spot-site
+	docker build -f Dockerfile.site --progress=plain -t filebrowser.site .
+	docker run -d --name=filebrowser-site filebrowser.site
+	sleep 3
+	docker cp "filebrowser-site":/srv/site/ site/public
+	docker rm -f filebrowser-site
+
+.PHONY: site-serve
+site-serve: ## Serve site for development
+	docker build -f Dockerfile.site.dev -t filebrowser.site.dev .
+	docker run --rm -it -p 8000:8000 -v $(CURDIR)/site:/build/ -v $(CURDIR)/README.md:/tmp/README.md filebrowser.site.dev
+
 ## Help:
 help: ## Show this help
 	@echo ''

README.md

@@ -1,3 +1,10 @@
+---
+hide:
+  - navigation
+  - toc
+---
+#
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/filebrowser/logo/master/banner.png" width="550"/>
 </p>
@@ -31,21 +38,21 @@ File Browser is a **create-your-own-cloud-kind** of software where you can insta
 
 |    Easy Login System     |     Sleek Interface      |     User Management      |
 | :----------------------: | :----------------------: | :----------------------: |
-| ![](./docs/assets/1.jpg) | ![](./docs/assets/2.jpg) | ![](./docs/assets/3.jpg) |
+| ![](./site/docs/assets/1.jpg) | ![](./site/docs/assets/2.jpg) | ![](./site/docs/assets/3.jpg) |
 
 
 |       File Editing       |     Custom Commands      |      Customization       |
 | :----------------------: | :----------------------: | :----------------------: |
-| ![](./docs/assets/4.jpg) | ![](./docs/assets/5.jpg) | ![](./docs/assets/6.jpg) |
+| ![](./site/docs/assets/4.jpg) | ![](./site/docs/assets/5.jpg) | ![](./site/docs/assets/6.jpg) |
 
 ## Install
 
-For information on how to install File Browser, please check [docs/installation.md](./docs/installation.md).
+For information on how to install File Browser, please check [installation](./site/docs/installation.md).
 
 ## Configuration
 
-For information on how to configure File Browser, please check [docs/configuration.md](./docs/configuration.md).
+For information on how to configure File Browser, please check [configuration](./site/docs/configuration.md).
 
 ## Contributing
 
-For information on how to contribute to the project, including how translations are managed, please check [docs/contributing.md](./docs/contributing.md).
+For information on how to contribute to the project, including how translations are managed, please check [contributing](./site/docs/contributing.md).

scripts/watch.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+# Initial setup
+cp /tmp/README.md /build/docs/index.md
+sed -i 's|site/docs/||g' /build/docs/index.md
+
+# Start mkdocs in the background
+mkdocs serve -a 0.0.0.0:8000 --dirtyreload &
+
+# Watch for changes in README.md
+while true; do
+  inotifywait -e modify /tmp/README.md
+  echo "README.md changed. Updating index.md..."
+  cp /tmp/README.md /build/docs/index.md
+  sed -i 's|site/docs/||g' /build/docs/index.md
+done
+

site/mkdocs.yml

@@ -0,0 +1,121 @@
+site_name: Filebrowser
+site_description: 'A web-based file browser and manager for your files'
+site_author: 'Filebrowser Community'
+site_url: 'https://filebrowser.org'
+
+repo_name: 'filebrowser/filebrowser'
+repo_url: 'https://github.com/filebrowser/filebrowser'
+edit_uri: 'edit/master/site/docs/'
+
+copyright: 'Copyright © 2025 Filebrowser Community'
+
+theme:
+  name: material
+  language: en
+  logo: logo.png
+  favicon: favicon.png
+  palette:
+    - scheme: default
+      primary: blue
+      accent: light blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: blue
+      accent: light blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.indexes
+    - navigation.top
+    - navigation.instant
+    - search.suggest
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.action.edit
+    - content.action.view
+    - toc.follow
+    - toc.integrate
+
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+    view: material/eye
+
+plugins:
+  - search:
+      separator: '[\\s\\-\\/]+'
+  - offline
+  - minify:
+      minify_html: true
+
+markdown_extensions:
+  - smarty
+  - sane_lists
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - meta
+  - md_in_html
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      use_pygments: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - callouts
+  - github-callouts
+
+extra:
+  generator: false
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/filebrowser/filebrowser
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/filebrowser/filebrowser
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Installation: installation.md
+      - Configuration: configuration.md
+      - Security: security.md
+  - Contributing:
+      - Contributing: contributing.md
+      - Code of Conduct: code-of-conduct.md

site/requirements.txt

@@ -0,0 +1,4 @@
+mkdocs-material
+mkdocs-minify-plugin
+mkdocs-redirects
+markdown-callouts