Open-sourced by the team at Monostream
Otter Docs is a context-aware documentation framework, featuring dynamic variable injection and a simple, yet powerful event API.
The documentation content is written in Markdown and lives in a Git repository. This enables non-technical users to write documentation without having to worry about implememtation and deployment. Changes made to the content Git repository are automatically published by Otter Docs.
Otter Docs is written in Go, TypeScript and builds upon the awesome VuePress project.
git clone https://github.com/monostream/otter-docs.git && cd otter-docs- Set
git.urlto your content git repository and configureingressinvalues.yaml helm upgrade --install otter-docs -f values.yaml ./chart
Docker image can be found on Docker Hub.
- Clear Separation of Concerns: Content vs. Technical Details
- Simple, yet powerful Event API
- dynamic variables injection from host app
- default values for variables
- Automatic Navigation and Sidebar
- Full Markdown support with Source-Code Highlighting
- Custom Themes
The content of Otter Docs is written in Markdown files that are stored in a separate git repository. The URL to this repository has to be configured in Otter Docs. See Configuration for more information.
The structure of the repository should follow this structure:
/
├── .otterdocs
│ ├── config.json # [Optional] config file
│ ├── logo.png # [Optional] logo
│ └── favicon.ico # [Optional] favicon
├── nav-item-1 # top-level directories map to navigation links
│ ├── readme.md # define title of navigation item, server as index page | Link: /nav-item-1
│ └── sidebar-item-1-1.md # documentation page, will appear in sidebar | Link: /nav-item-1/sidebar-item-1-1.html
└── nav-item-2 # ...
├── readme.md # ... | Link: /nav-item-2
└── sidebar-item-2-1.md # ... | Link: /nav-item-2/sidebar-item-2-1.html
Check out the example on how to send and recieve messages to and from Otter Docs.
Otter Docs can be deployed as a context-aware documentaion, living in a sidebar of another application (called "host application"). The Event API enables bi-directional communication between the two applications. This API informs Otter Docs about the currently active page in the host application. This can be useful to show relevant documentation articles to the user.
Here is an overview of all events:
| Event | Type | Description |
|---|---|---|
| Ready | /otter-docs/ready |
Otter Docs is ready (sent from Otter Docs --> Host Application |
| Navigate | /otter-docs/navigate |
Host application navigated to a new path |
| Inject | /otter-docs/inject |
Send variables from host application to Otter Docs |
Top-level directories or files are mapped to navigation items. To customize the label text, place a readme.md file inside and set the title frontmatter attribute. Learn more about pages in the official VuePress v2 documentation.
Pages inside directories are mapped to entries in the sidebar.
Heading inside a page are mapped to sub-entries in the sidebar.
Note: Currently pages cannot be nested depper than one level.
For rendering Markdown to HTML content, Otter Docs uses VuePress v2. This enables Otter Docs to support many powerful features, such as code blocks with hightlighting and table of contents.
Check out the official documentation to learn all about the Markdown features of Otter Docs.
To configure Otter Docs, create a file /.otterdocs/config.json in your content git repository. The following options are available
{
"name": "Otter Docs", // name of the documentation used as title
"tagline": "Powerful, Context-Aware Documentation Framework", // tagline on the home page
"getStartedLink": "/docs/Projects/", // link of the "Getting Started" button on the home page
"colors": { // custom theme
"brand": "#ff1a8c", // brand color used for buttons, links, …
"brandLight": "#ff3399" // light brand color used for hover states of buttons, links, …
},
"bindings": { // object mapping path of the host application to docs path (using path-to-regexp)
"/": "/docs/Projects/", // when host navigates to / --> docs navigate to /docs/Projects/
"/project/:projectId": "/docs/Projects/Details.html" // when host navigates to /project/1 --> docs navigate to /docs/Projects/Details.html
}
}To change the logo displayed in the navigation, create a file called /.otterdocs/logo.png in your content git repository.
Similarly, to set a custom favicon, copy it to /.otterdocs/favicon.ico.
To customize the colors of Otter Docs, config.json supports an optional object colors. In this objects two colors can be defined:
brand(used for buttons, links, …)brandLight(used for hover states of buttons, links, …)
{
// ...
"colors": {
"brand": "#ff1a8c",
"brandLight": "#ff3399"
}
}- Watch git repository for changes
- Trigger rebuild
- Serve docs
- Dynamically generate navigation and sidebar structure
- Parse and sanatize
config.json - Apply
config.json - Render Markdown to HTML
- Listen for Events from host application
- Parse path binding Regexp
- Handle navigation
To run the Otter Docs Server locally you can choose between Docker or Go.
Build and run the go source-code locally with the following command.
go build .
./otter-docs
If you have docker installed on your system, you can use the following command to build and run the source-code. Environment variables can be configured in a .env file in the root of the project.
docker build . -t otter-docs
docker run -p 8080:8080 -it --env-file ./.env --rm otter-docsThe following environment varaibles are available to configure Otter-Docs server.
| Name | Default | Description | Required |
|---|---|---|---|
| GIT_URL | None | URL to the content git repository. Example: https://username:[email protected]/myRepo.git | Yes |
| GIT_BRANCH | main | The branch that should be published and monitored by Otter Docs | No |