Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/traefik/structor
[Messor Structor 🐜] Manage multiple versions of a Mkdocs documentation
https://github.com/traefik/structor
documentation-tool mkdocs versioning
Last synced: about 1 month ago
JSON representation
[Messor Structor 🐜] Manage multiple versions of a Mkdocs documentation
- Host: GitHub
- URL: https://github.com/traefik/structor
- Owner: traefik
- License: apache-2.0
- Created: 2018-01-16T10:26:18.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-05-15T22:41:28.000Z (over 1 year ago)
- Last Synced: 2024-09-26T21:04:20.484Z (about 1 month ago)
- Topics: documentation-tool, mkdocs, versioning
- Language: Go
- Homepage:
- Size: 223 KB
- Stars: 37
- Watchers: 19
- Forks: 8
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - traefik/structor - [Messor Structor 🐜] Manage multiple versions of a Mkdocs documentation (others)
README
# Messor Structor: Manage multiple documentation versions with Mkdocs.
[](https://github.com/traefik/structor/releases/latest)
[](https://github.com/traefik/structor/actions)
Structor use git branches to create the versions of a documentation, only works with Mkdocs.
To use Structor a project must respect [semver](https://semver.org) and creates a git branch for each `MINOR` and `MAJOR` version.
Created for [Traefik](https://github.com/traefik/traefik) and used by:
* [Traefik](https://github.com/traefik/traefik) for https://docs.traefik.io
* [Redis Labs](https://redislabs.com/) https://redislabs.com/community/oss-projects/
* [JanusGraph](https://github.com/JanusGraph/janusgraph) for https://docs.janusgraph.org
* [ONOS Project](https://github.com/onosproject) for https://docs.onosproject.org
* [Drasyl](https://gitlab.com/drasyl/drasyl) for https://docs.drasyl.org
## Prerequisites
* [git](https://git-scm.com/)
* [Docker](https://www.docker.com/)
* `requirements.txt`, `mkdocs.yml`, and a Dockerfile.
## Description
For the following git graph:
```
* gaaaaaaag - (branch master) commit
| * faaaaaaaf - (branch v1.2) commit
| * eaaaaaaae - commit
|/
* haaaaaaah - commit
| * kaaaaaaak - (branch v1.1) commit
| * jaaaaaaaj - commit
|/
* iaaaaaaai - commit
| * daaaaaaad - (branch v1.0) commit
| * caaaaaaac - commit
|/
* baaaaaaab - commit
* aaaaaaaaa - initial commit
```
Structor generates the following files structure:
```
. (latest, branch v1.2)
├── index.html
├── ...
├── v1.0 (branch v1.0)
│ ├── index.html
│ └── ...
├── v1.1 (branch v1.1)
│ ├── index.html
│ └── ...
└── v1.2 (branch v1.2)
├── index.html
└── ...
```
If the content from `.` is served on `mydoc.com`, documentation will be available at the following URLs:
- `http://mydoc.com` (latest, branch v1.2)
- `http://mydoc.com/v1.0` (branch v1.0)
- `http://mydoc.com/v1.1` (branch v1.1)
- `http://mydoc.com/v1.2` (branch v1.2)
The multi version menu is created from templates provided by the following options:
- `--menu.js-url` (or `--menu.js-file`)
- `--menu.css-url` (or `--menu.css-file`)
## Configuration
```yaml
Messor Structor: Manage multiple documentation versions with Mkdocs.
Usage:
structor [flags]
structor [command]
Available Commands:
help Help about any command
version Display version
Flags:
--debug Debug mode.
--dockerfile-name string Search and use this Dockerfile in the repository (in './docs/' or in './') for building documentation. (default "docs.Dockerfile")
-d, --dockerfile-url string Use this Dockerfile when --dockerfile-name is not found. Can be a file path. [required]
--exclude strings Exclude branches from the documentation generation.
--exp-branch string Build a branch as experimental.
--force-edit-url Add a dedicated edition URL for each version.
-h, --help help for structor
--image-name string Docker image name. (default "doc-site")
--menu.css-file string File path of the template of the CSS file use for the multi version menu.
--menu.css-url string URL of the template of the CSS file use for the multi version menu.
--menu.js-file string File path of the template of the JS file use for the multi version menu.
--menu.js-url string URL of the template of the JS file use for the multi version menu.
--no-cache Set to 'true' to disable the Docker build cache.
-o, --owner string Repository owner. [required]
-r, --repo-name string Repository name. [required]
--rqts-url string Use this requirements.txt to merge with the current requirements.txt. Can be a file path.
--version version for structor
```
The environment variable `STRUCTOR_LATEST_TAG` allow to override the latest tag name obtains from GitHub.
The [sprig](http://masterminds.github.io/sprig/) functions for Go templates can be used inside the JS template file.
## Download / CI Integration
```bash
curl -sfL https://raw.githubusercontent.com/traefik/structor/master/godownloader.sh | bash -s -- -b $GOPATH/bin v1.7.0
```
## Examples
A simple example is available on the repository https://github.com/mmatur/structor-sample.
With menu template URL:
```shell
sudo ./structor -o traefik -r traefik \
--dockerfile-url="https://raw.githubusercontent.com/traefik/traefik/master/docs.Dockerfile" \
--menu.js-url="https://raw.githubusercontent.com/traefik/structor/master/traefik-menu.js.gotmpl" \
--exp-branch=master --debug
```
With local menu template file:
```shell
sudo ./structor -o traefik -r traefik \
--dockerfile-url="https://raw.githubusercontent.com/traefik/traefik/master/docs.Dockerfile" \
--menu.js-file="~/go/src/github.com/traefik/structor/traefik-menu.js.gotmpl" \
--exp-branch=master --debug
```
## The Mymirca colony
- [Myrmica Lobicornis](https://github.com/traefik/lobicornis) 🐜: Update and merge pull requests.
- [Myrmica Aloba](https://github.com/traefik/aloba) 🐜: Add labels and milestone on pull requests and issues.
- [Messor Structor](https://github.com/traefik/structor) 🐜: Manage multiple documentation versions with Mkdocs.
- [Lasius Mixtus](https://github.com/traefik/mixtus) 🐜: Publish documentation to a GitHub repository from another.
- [Myrmica Bibikoffi](https://github.com/traefik/bibikoffi) 🐜: Closes stale issues
- [Chalepoxenus Kutteri](https://github.com/traefik/kutteri) 🐜: Track a GitHub repository and publish on Slack.
- [Myrmica Gallienii](https://github.com/traefik/gallienii) 🐜: Keep Forks Synchronized
## What does Messor Structor mean?
