# Overview (/docs/documentation)

Contributions to the documentation are welcome! This guide explains how to contribute to the LibreChat documentation by writing and formatting new documentation. Our website is built with Nextra 3 and our docs use the `.mdx` format (augmented markdown).

### When to Write a Doc vs. a Blog Post

<Callout type="info" title="Blog vs Docs">
Consider publishing a blog post when a document is an extension of an existing one, relates to a specific situation, or requires external maintenance (features not actively used by the team).

**See: [Contributing to Blog](/blog/2024-04-17_blog_guide)**

</Callout>

## Getting Started

- Fork the LibreChat Documentation repository: [https://github.com/LibreChat-AI/librechat.ai](https://github.com/LibreChat-AI/librechat.ai)

- Create a branch on your fork, name it properly, and link it to the original repository.

```sh filename="Download your LibreChat.ai branch"
git clone -b branch-name https://github.com/username/librechat.ai.git
```

> Replace `branch-name` and `username` with your details

## Creating New Documents

To create a new document:

- Use the `.mdx` file extension (see [MDX documentation](https://mdxjs.com/) for more info).
- Name files using **lowercase letters** and **underscores** (e.g., `documentation_guidelines.mdx`).
- Place new documents in the relevant folder/sub-folder under `./docs`.
- Add the document to the table of contents in the `_meta.ts` file of the folder where your document is located. If you don't add it, it will be alphabetically sorted after the ordered docs.

## Markdown Formatting Guidelines

- Use headings and subheadings with `#`, `##`, and `###`.
  - Use `#` for the document title (**only one main title per document is allowed**).
  - Use `##` for main sections.
  - Use `###` for sub-sections within a section.
- Use `**` to make text **bold** and highlight important information (do not use in place of a heading).
- Use URL paths to link to other documents (e.g., `/docs/documentation` points the current [doc](/docs/documentation)).
- You can use HTML, TS, and JS to add additional features to a document.
- Ensure any HTML has closing tags (e.g., `<img src="" />` or `<a href="link"></a>`).
- Do not use HTML comments; instead, use [Markdown comments](https://gist.github.com/jonikarppinen/47dc8c1d7ab7e911f4c9?permalink_comment_id=4272770#gistcomment-4272770) **only if the text is actually hidden**.

### Docs Resources

<Callout type="tip" title="Docs Resources">

See some integrated components examples:

- [Components Examples](/docs/documentation/examples)

For more information, refer to:

- [Nextra](https://nextra.site/docs/docs-theme/start)
- [Nextra 3](https://the-guild.dev/blog/nextra-3#intro)
- [MDX](https://mdxjs.com/)

</Callout>

## Document Metadata

Add metadata to the header of your document using the following format:

> Note: The `ogImage` field is optional and can be omitted altogether. It is used to specify the image that will be displayed when sharing your document on social media platforms.

```yaml filename="metadata example:"
---
title: Document Title
description: This description will be used in social cards and search engine results.
ogImage: /images/docs/<category>/image.png (optional)
---
```

## Assets

Whenever possible, upload assets (e.g., images) to GitHub instead of storing them in the `/public` folder. This helps keep your repository organized and makes it easier to manage your assets.

### Images

**Note: In the following example:**
  - I provided screenshots for both light and dark mode.
  - I used `Image from 'next/image'` which gave me 4x improvement on the image file size for better performance.

see the following example in action here: [User Guides](/docs/user_guides)

```mdx filename="Example"
import Image from 'next/image'

<div style={{padding: "20px", display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column"}}>
  <div className="image-light-theme">
    <Image src="https://github.com/danny-avila/LibreChat/assets/32828263/cf0f3231-287a-407f-bd4d-3d5bad94e893" alt="ipad-light" width={1024} height={512} style={{borderRadius: "5px"}} />
  </div>

  <div className="image-dark-theme">
    <Image src="https://github.com/danny-avila/LibreChat/assets/32828263/a03ee02d-5099-4220-95b0-bfa2d3b00b4d" alt="ipad-dark" width={1024} height={512} style={{borderRadius: "5px"}} />
  </div>
</div>
```

### How to Upload Images and Videos on GitHub

<Callout title="Method A" emoji="🅰️" collapsible>
    - Go to the LibreChat repository
    - Find a random conversation or PR
    - Paste an image from your clipboard into the text input box. It will automatically be converted into a URL.
    - Copy and paste the resulting URL in your document. (Then exit the page without actually posting the comment.😉)

    ![image](https://github.com/danny-avila/LibreChat/assets/32828263/c1612f93-a6c0-4af7-9965-9f83872cff00)

</Callout>

<Callout title="Method B" emoji="🅱️" collapsible>
    - Upload directly from the web UI:

    ![image](https://github.com/danny-avila/LibreChat/assets/32828263/4f138ab4-31a5-4fae-a459-5335e5ff25a8)

</Callout>

## Test the Docs

<Callout type="warning" title="Before you submit">
### Review carefully before submitting your PR

Before submitting a PR for your blog post, **always** test to ensure everything looks and functions as intended.

#### Check the following:

- Your new document(s) for layout, accuracy and completeness
- The document's position in the Table of Contents (ToC)
- The image and link in your document

#### To test:

1. Prepare the environment by running `pnpm install`
2. Start the dev server with `pnpm dev`
3. Test the build by running `pnpm build` followed by `pnpm start`

</Callout>