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)

go run main.go

Build

go build -o chronos main.go

Run (prod)

./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:

{
  "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:

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:

---
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:

{
  "status": "ok"
}

Check if a repository is available.

URL: http://localhost:8080/{repoId}
Method: GET
Response:

{
  "status": "ok"
}

Get Repos

Get a list of available repositories.

URL: http://localhost:8080/repos
Method: GET
Response:

  {
    "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:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "Title": "Test Article",
    "Description": "This is a test article written in English.",
    "PublicationDate": "2023-06-10",
    "Authors": ["mirkobrombin"],
    "Body": "..."
  }
]

kbdharun/Chronos