Autologyx Docs

Appearance

Contributing ​

This page outlines the rules to follow when writing documents. Please review them before creating any new content or making edits.

TIP

Make sure to first scroll through Vitepress official documentation.

General rules ​

  • Keep 120 characters for line (if possible).
  • Keep documents small. Split files for multiple if that can be realized.
  • Follow API standards

TIP

Please refer to Vitepress Markdown guide.

File naming ​

There are a few file naming rules that help keep the codebase consistent and thus more readable.

  • Files and folders should use kebab-case, e.g. object-classes.md.
  • Files should be named after the resource they describe, e.g. object-record-permission-sets.md. The only exception to this rule are index.md files, which serve as a fallback files for directories.

File structure ​

The codebase is organized with a clear folder structure that directly reflects the logical layout seen by the end user. The purpose of this structure is to ensure that file and folder names match the way documentation is presented, with each path representing the actual URL seen in the browser.

  • API-related content lives in the ./docs/api folder.
    • Catalyst API reference documentation resides in the ./docs/api/catalyst folder.
    • Event History API reference documentation is stored in the ./docs/api/event-history folder.
    • API standards documentation is located in the ./docs/api/standards folder.
  • Additional "helps" not directly related to the API are located in the ./docs/helps folder.

Each file and folder in the structure should match its respective URL path. For example, if the URL is /helps/enviroments/tenants, the corresponding file should be nested under ./docs/helps/enviroments/tenants.md to ensure consistency.

Note

Each directory can contain its own media folder, reserved exclusively for media files (e.g., images, videos) used by its child files and folders. This keeps all media assets organized and ensures that each section’s assets are easy to locate without cluttering other directories.

When a page includes a sidebar, the sections and nesting in the sidebar should also be reflected in both the URL and folder structure. This approach ensures a consistent and intuitive experience for users, with clear divisions between different content sections.

For example

If the /api/catalyst/ page has a "Resources" section in its sidebar, then this structure should be mirrored in the URL and folder layout. So if there’s a e.g. "Roles" document under "Resources", the correct URL would be /api/catalyst/resources/roles.html, and the file structure should be ./docs/api/catalyst/resources/roles.md.

This alignment between sidebar organization, URLs, and file structure keeps different sections distinct and prevents content from different topics or sections from being mixed up in the codebase.

Reasoning ​

Having the file structure mirror the URL path is essential for several reasons:

  • Logical Organization: This approach keeps the documentation logically structured, making it easier for both users and developers to find content intuitively.
  • Edit Page Button Functionality: Each page includes an "Edit Page" button at the bottom, allowing users and developers to jump directly to the corresponding file in GitLab. This link relies on the URL structure, so if the file structure in the codebase doesn’t match the URL path, the "Edit Page" feature will not work correctly.
  • Maintainability and Consistency: A consistent structure between URLs and file paths simplifies maintenance and helps avoid confusion when updating or adding content.

Headings rules ​

  • Main title of a document should be level-1 heading - #.
  • Sections should start from level-2 - ##.
markdown
# Document title

## Section 1

### Section 1.1

#### Section 1.1.1

### Section 1.2

## Section 2

Document templates ​

When documenting a new API resource simply copy, paste and adjust the prepared template file located under ./docs/contributing/api-resource-template.md. Do not re-order sections from the template.

Some pages, such as /api/catalyst, have sidebars which are defined in config.mts file. In these scenarios, new pages must be appended to a given sidebar, by editing its corresponding configuration file. Sidebar configs can be found under ./docs/.vitepress/consts directory.

Important

Sidebar items should be sorted alphabetically.

Helpers ​

  • Pycharm has built-in Markdown editor. In context menu there is an option to paste link, image, table, TOC. Click right mouse button -> Insert and choose option.
  • To create table or copy it from other editor use tablesgenerator