Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vanilla-os/chronos
Chronos is a simple, fast and lightweight documentation server written in Go.
https://github.com/vanilla-os/chronos
chronos documentation documentation-server hacktoberfest vanillaos
Last synced: about 2 months ago
JSON representation
Chronos is a simple, fast and lightweight documentation server written in Go.
- Host: GitHub
- URL: https://github.com/vanilla-os/chronos
- Owner: Vanilla-OS
- License: gpl-3.0
- Created: 2023-06-27T06:34:24.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-01T10:03:50.000Z (2 months ago)
- Last Synced: 2024-11-01T11:17:18.052Z (2 months ago)
- Topics: chronos, documentation, documentation-server, hacktoberfest, vanillaos
- Language: Go
- Homepage:
- Size: 201 KB
- Stars: 18
- Watchers: 4
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Chronos
A simple, fast and lightweight documentation server written in Go.
## Features
- API based response
- Markdown support
- Search
- Localization
- Git based and/or local articles storage
- Ristretto based cache (more cache backends coming soon)
- Multi-repository support
## Configuration
Edit the `config/chronos.json` file to configure the server.
## Run (dev)
```bash
go run main.go
```
## Build
```bash
go build -o chronos main.go
```
## Run (prod)
```bash
./chronos
```
## Repositories
Chronos supports multiple repositories, both local and Git based. This allows you
to have a single server for multiple projects or multiple repositories for a single project.
Repositories can be configured in the `chronos.json` file as follows:
```json
{
"port": "8080",
"gitRepos": [
{
"id": "vosDocs",
"url": "https://github.com/Vanilla-OS/documentation"
},
{
"id": "vosVib",
"url": "https://github.com/Vanilla-OS/vib",
"rootPath": "docs/articles"
}
],
"localRepos": [
{
"id": "myAwesomeProject",
"path": "/myAwesomeProject/documentation"
}
]
}
```
Each repository must have a unique `id`, Chronos requires it to identify the repository
when requesting articles.
### Local repositories
Each local repository must contain an `articles` folder with the following structure:
```txt
documentation
├──articles
├─── en
│ └─── article1.md
└─── it
└─── article1.md
```
### Git repositories
You can use a Git repositories as well, just add them to the `GitRepos` array in the `chronos.json` file,
Chronos will automatically clone them and update on each restart.
## Background updates
In the current version, automatic updates are in experimental stage and are not yet fully implemented.
## Article Structure
Each article must have a specific structure, here's an example:
```markdown
---
Title: My Awesome Article
Description: This is a test article written in English.
PublicationDate: 2024-02-16
Authors: [johnDoe]
Tags: [tag1, tag2]
---
# My Awesome Article
This is a test article written in English.
```
The article must start with a YAML header, followed by the article body.
## API Reference
### Get Status
Get the status of the server.
- **URL**: `http://localhost:8080/`
- **Method**: GET
- **Response**:
```json
{
"status": "ok"
}
```
Check if a repository is available.
- **URL**: `http://localhost:8080/{repoId}`
- **Method**: GET
- **Response**:
```json
{
"status": "ok"
}
```
### Get Repos
Get a list of available repositories.
- **URL**: `http://localhost:8080/repos`
- **Method**: GET
- **Response**:
```json
{
"Id": "remote1",
"Count": 52,
"Languages": [
"bn",
"de",
"en",
"es",
"fr",
"pl",
"ta",
"th",
"uk"
],
"FallbackLang": "",
"FallbackEnabled": false
},
{
"Id": "remote2",
"Count": 8,
"Languages": [
"en"
],
"FallbackLang": "",
"FallbackEnabled": false
},
{
"Id": "remote3",
"Count": 1,
"Languages": [
"en"
],
"FallbackLang": "",
"FallbackEnabled": true
}
]
```
### Get Articles
Get a list of articles, grouped by language.
- **URL**: `http://localhost:8080/{repoId}/articles/{lang}`
- **Method**: GET
- **Response**:
```json
{
"title": "repoId",
"SupportedLang": ["en", "it"],
"tags": ["tag1", "tag2"],
"articles": {
"en": {
"articles_repo/articles/en/test.md": {
"Title": "Test Article",
"Description": "This is a test article written in English.",
"PublicationDate": "2023-06-10",
"Authors": ["mirkobrombin"],
"Tags": ["tag1", "tag2"],
"Body": "..."
}
},
"it": {
"articles_repo/articles/it/test.md": {
"Title": "Articolo di Test",
"Description": "Questo è un articolo di test scritto in italiano.",
"PublicationDate": "2023-06-10",
"Authors": ["mirkobrombin"],
"Tags": ["tag2"],
"Body": "..."
}
}
}
}
```
### Get Supported Languages
Get a list of supported languages.
- **URL**: `http://localhost:8080/{repoId}/langs`
- **Method**: GET
- **Response**:
```json
{
"SupportedLang": ["en", "it"]
}
```
### Get Article by Language and Slug
Get a specific article by providing its language and slug.
- **URL**: `http://localhost:8080/{repoId}/articles/en/test`
- **Method**: GET
- **Response**:
```json
{
"Title": "Test Article",
"Description": "This is a test article written in English.",
"PublicationDate": "2023-06-10",
"Authors": ["mirkobrombin"],
"Body": "..."
}
```
### Search Articles
Search articles based on a query string.
- **URL**: `http://localhost:8080/{repoId}/search/{lang}?q=test`
- **Method**: GET
- **Response**:
```json
[
{
"Title": "Test Article",
"Description": "This is a test article written in English.",
"PublicationDate": "2023-06-10",
"Authors": ["mirkobrombin"],
"Body": "..."
}
]
```