https://github.com/snipem/monako
Multi repository static site generator for Markdown and Asciidoc documentation
https://github.com/snipem/monako
documentation-toolchain git hugo
Last synced: 3 months ago
JSON representation
Multi repository static site generator for Markdown and Asciidoc documentation
- Host: GitHub
- URL: https://github.com/snipem/monako
- Owner: snipem
- License: apache-2.0
- Created: 2019-10-18T17:00:25.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-26T19:37:59.000Z (11 months ago)
- Last Synced: 2025-02-07T06:41:28.435Z (3 months ago)
- Topics: documentation-toolchain, git, hugo
- Language: Go
- Homepage:
- Size: 3.55 MB
- Stars: 38
- Watchers: 3
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# monako
!!!
**This project is no longer actively maintained. Use it at your own risk.**
!!!
## About
[](https://codecov.io/gh/snipem/monako)
[](https://goreportcard.com/report/github.com/snipem/monako)
[](https://godoc.org/github.com/snipem/monako)
[](https://codeclimate.com/github/snipem/monako/maintainability)
----
A less opinionated document aggregator and publisher. Easier to use and to adapt than Antora, Hugo, JBake and the likes.
----
## Purpose
Monako abstracts the complexity of collecting documentation from a configurable amount of Git repositories (origins).
Monako uses [Hugo](https://gohugo.io) as a static site generator but hides it to the user. It also uses the great [Hugo Book Theme](https://github.com/alex-shpak/hugo-book) which I forked at [Monako Book](https://github.com/snipem/monako-book).
## How Monako works
## Usage
```help
$ monako -h
Usage of monako:
-base-url string
Custom base URL
-config string
Configuration file (default "config.monako.yaml")
-fail-on-error
Fail on document conversion errors
-menu-config string
Menu file for monako-book theme (default "config.menu.md")
-compose
Only compose the Monako structure
-render
Only render HTML files from an existing Monako structure
-trace
Enable trace logging
```
A Docker image is available from [Github Packages](https://github.com/snipem/monako/pkgs/container/monako).
## Configuration
### Configuration of Origins
```yaml
---
baseURL : "https://example.com/"
title : "My Projects"
whitelist:
- ".md"
- ".adoc"
- ".jpg"
- ".svg"
- ".png"
origins:
- src: https://github.com/snipem/commute-tube
branch: master
docdir: .
targetdir: docs/commute
- src: https://github.com/snipem/monako
branch: develop
docdir: doc
targetdir: docs/monako
```
### Configuration of Menus
```markdown
- **My Projects**
- [Commute Tube]({{< relref "/docs/commute/readme" >}})
- [Monako]({{< relref "/docs/monako/readme" >}})
...
```
### Configuration of Documents
Monako supports all [Hugo Frontmatter](https://gohugo.io/content-management/front-matter/) types (YAML, TOML and JSON).
Monako converts them to YAML.
Add frontmatter as you wish at long as it's supported by Hugo and the Theme.
#### Monako specific options
Hide Git links like "edit this page" and "last edit by". Add this line to the frontmatter of the document:
```yaml
MonakoGitLinks = false
```
### Screenshot
## Design Goals
* Make it simple and stupid, single binary with no dependencies ✓
* Git clone existing repositories ✓
* Don't attempt to change their structure ✓
* Transform all documents below a specific structure ✓
* Use Antora like configuration file for main structure ✓
* Support Mermaid ✓
## Features
* Multi repository document fetching
* Bundled dependencies (minus Asciidoctor)
## Development
Init with `make init`
## Improvements
* Support edit this page links with links to origin repository. Book theme provides a [similar feature](https://github.com/alex-shpak/hugo-book/search?q=BookRepo&unscoped_q=BookRepo).