Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/docat-org/docat
Host your docs. Simple. Versioned. Fancy.
https://github.com/docat-org/docat
docs fancy hacktoberfest hosting selfhosted versioning
Last synced: 3 months ago
JSON representation
Host your docs. Simple. Versioned. Fancy.
- Host: GitHub
- URL: https://github.com/docat-org/docat
- Owner: docat-org
- License: mit
- Created: 2019-11-08T13:38:54.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-05-02T02:16:11.000Z (6 months ago)
- Last Synced: 2024-05-02T06:07:20.950Z (6 months ago)
- Topics: docs, fancy, hacktoberfest, hosting, selfhosted, versioning
- Language: TypeScript
- Homepage:
- Size: 3.43 MB
- Stars: 734
- Watchers: 9
- Forks: 49
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - docat-org/docat - Host your docs. Simple. Versioned. Fancy. (hacktoberfest)
- jimsghstars - docat-org/docat - Host your docs. Simple. Versioned. Fancy. (TypeScript)
README
![docat](doc/assets/docat-teaser.png)
**Host your docs. Simple. Versioned. Fancy.**
[![build](https://github.com/docat-org/docat/workflows/docat%20ci/badge.svg)](https://github.com/docat-org/docat/actions)
[![Gitter](https://badges.gitter.im/docat-docs-hosting/community.svg)](https://gitter.im/docat-docs-hosting/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)## Getting started
The simplest way is to build and run the docker container,
you can optionally use volumes to persist state:```sh
# run container in background and persist data (docs, nginx configs and tokens database)
# use 'ghcr.io/docat-org/docat:unstable' to get the latest changes
mkdir -p docat-run/doc
docker run \
--detach \
--volume $PWD/docat-run:/var/docat/ \
--publish 8000:80 \
ghcr.io/docat-org/docat
```Go to [localhost:8000](http://localhost:8000) to view your docat instance:
![docat screenshot](doc/assets/docat-screenshot.png)
### Local Development
For local development, first configure and start the backend (inside the `docat/` folder):
```sh
# create a folder for local development (uploading docs)
DEV_DOCAT_PATH="$(mktemp -d)"# install dependencies
poetry install# run the local development version
DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat
```After this you need to start the frontend (inside the `web/` folder):
```sh
# install dependencies
yarn install --frozen-lockfile# run the web app
yarn serve
```For more advanced options, have a look at the
[backend](docat/README.md) and [web](web/README.md) docs.### Push Documentation to docat
The preferred way to push documentation to a docat server is using the [docatl](https://github.com/docat-org/docatl)
command line application:```sh
docatl push --host http://localhost:8000 /path/to/your/docs PROJECT VERSION
```There are also docker images available for CI systems.
#### Using Standard UNIX Command Line Tools
If you have static html documentation or use something like
[mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/), ...
to generate your documentation, you can push it to docat:```sh
# create a zip of your docs
zip -r docs.zip /path/to/your-docs
# upload them to the docat server (replace PROJECT/VERSION with your projectname and the version of the docs)
curl -X POST -F "[email protected]" http://localhost:8000/api/PROJECT/VERSION
```When you have multiple versions you may want to tag some version as **latest**:
```sh
# tag the version VERSION of project PROJECT as latest
curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest
```Same thing with `docatl`:
```sh
# tag the version VERSION of project PROJECT as latest
docatl tag --host http://localhost:8000 PROJECT VERSION latest
```## Advanced Frontend `config.json`
It is possible to configure some things after the fact.
1. Create a `config.json` file
2. Mount it inside your docker container `--volume /path/to/config.json:/var/docat/doc/config.json`Supported config options:
- headerHTML
## Advanced System Config
Further proxy configurations can be done through the following environmental variables:
| Variable | Default (Link to Definition) | Description |
|---|---|---|
| MAX_UPLOAD_SIZE | [100M](./Dockerfile) | Limits the size of individual archives posted to the API |