Documentation Contribution Guidelines
This document explains how to contribute to the LibreChat documentation by writing and formatting new documentation.
New Documents
- Use lowercase letters and underscores to name new document files (e.g.: documentation_guidelines.md ).
- For new features, create new documentation and place it in the relevant folder/sub-folder under ../docs .
-
If the feature adds new functionality, add it to the appropriate section in the main
README.mdand../docs/index.md. -
When creating a new document,
add it to the table of contents in the
index.mdfile of the folder where your document is located.
Markdown Formatting
-
Use
#,##, and###for headings and subheadings. -
Use
#for the document title.- ❗ Only one main title per document is allowed
-
Use
##for the main sections of the document. -
Use
###for the sub-sections within a section. -
Use
**to make text bold and highlight important information (do not use in place of a heading). - Use relative paths for links to other documents.
- You can use HTML to add additional features to a document.
-
Highlight keystrokes with
+(example:++ctrl+alt+del++🟰 Ctrl + Alt + Del ) -
Make sure any HTML has closing tags; i.e.:
<img src="" />or<a href="link"></a> - HTML comments are not allowed. Use Markdown comments instead, and only if the text is actually hidden.
- 🌐 see the MKDocs Material documentation for more information: MKDocs Material Reference
Document Metadata
- Add metadata in the header of your document following this format:
metadata example:
---
title: 😊 Document Title
description: This description will be used in social cards and search engine results.
weight: 0
---
-
title:Begin with an emoji representing your new document, followed by a descriptive title. -
description:A brief description of the document's content. -
weight:Setting the weight in the document metadata will influence its position in the table of contents. Lowest weights are placed first. If not set, it defaults to0. When multiple docs have the same weight, they are sorted alphabetically.
Important Notes
- 🗃️ Keep the documentation organized and structured
- 🙅 Do not add unrelated information to an existing document. Create a new one if needed.
- 📌 Upload all assets (images, files) directly from GitHub when editing the document (see tip below).
Upload Assets on GitHub
Example
- Go to the LibreChat repository, find a conversation, and paste an image from your clipboard into the text input box. It will automatically be converted into a URL you can use in your document. (Then exit the page without actually posting the comment.😉)
Get the link from a text input box:
Alternative method
Upload directly from the web UI:
Testing New Documents
- When adding new documents, it is important to test them locally using MkDocs to ensure correct formatting and proper organization in the table of contents: specifically in index.md and in the left panel of each category. Make sure the document position match in both.
Setup MkDocs Locally
- Requirement: Python 3.3 and later (on older versions you will need to install virtualenv)
Material for MkDocs Installation
- We are using MkDocs Material and multiple plugins. All of them are required to properly test new documentation.
Install Requirements:
python -m venv .venv
. .venv/bin/activate
pip install -r ./docs/src/requirements.txt
Running MkDocs
- Use this command to start MkDocs:
- ✅ Look for any errors in the console logs and fix them whenever possible.
-
🌐 Access the locally running documentation website at
http://127.0.0.1:8000/.
Tips
Tips
- You can check the code of this document to see how it works.
- You should run MkDocs locally to test more extensive documentation changes.
- You can ask GPT, Claude or any other AI for help with proofreading, syntax, and markdown formatting.