Skip to content

Remove docs build lint and Browserslist warnings #1909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
marcleblanc2 wants to merge 4 commits into from
Closed

Remove docs build lint and Browserslist warnings #1909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4501910
docs: remove build lint warnings
marcleblanc2 Sep 11, 2026
16956ec
Fix README markdownlint findings
marcleblanc2 Sep 11, 2026
425dd0f
Fix AGENTS.md markdownlint findings and drop stale runLLM section
marcleblanc2 Sep 11, 2026
c5a6f80
Drop the AI chat note from AGENTS.md
marcleblanc2 Sep 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 24 additions & 46 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,50 +2,28 @@

## Build Commands

- **Type Check**: `npx tsc --noEmit`
- **Build**: `npm run build`
- **Dev**: `npm run dev`
- **Lint**: `npm run lint`
- **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames, images); `npm run build` runs them first, so any finding fails a deploy
- **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links; see `dev/check-links.mjs`; the build runs it without flags, so only dead page links fail a deploy). When moving a page or renaming a heading, update every link to it; a redirect in `src/data/redirects.ts` does not satisfy the check. Link to this site with relative paths (`/admin/config/site-config`), never `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`. To also probe the external links you added: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)`
- **Prove changed links resolve on a deploy**: `node dev/verify-links-live.mjs --site <vercel-preview-url>` prints a Markdown table for the PR description

## AI Chat Integration

This site uses **runLLM** for the AI chat widget. The integration is implemented via:

- **Location**: `src/app/layout.tsx`
- **Widget**: runLLM script loaded via Next.js `<Script>` component
- **Configuration**:
- Position: BOTTOM_RIGHT
- Theme color: #FF5543 (Sourcegraph brand color)
- Button text: "Ask AI"
- Keyboard shortcut: Mod+j

### runLLM Configuration

To update the runLLM assistant ID or other settings, modify the Script component in `src/app/layout.tsx`:

```tsx
<Script
id="runllm-widget-script"
type="module"
src="https://widget.runllm.com"
crossOrigin=""
runllm-keyboard-shortcut="Mod+j"
runllm-name="Sourcegraph AI Assistant"
runllm-position="BOTTOM_RIGHT"
runllm-assistant-id="YOUR_ASSISTANT_ID" // Update this
runllm-theme-color="#FF5543"
runllm-floating-button-text="Ask AI"
async
/>
- **Type Check**: `npx tsc --noEmit`
- **Build**: `npm run build`
- **Dev**: `npm run dev`
- **Lint**: `npm run lint`
- **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames,
images); `npm run build` runs them first, so any finding fails a deploy
- **Prove changed links resolve on a deploy**:
`node dev/verify-links-live.mjs --site <vercel-preview-url>` prints a
Markdown table for the PR description

### Links

- `npm run check -- links --check-anchors --check-self-links`. CI comments on
PRs that break links; see `dev/check-links.mjs`. The build runs it without
flags, so only dead page links fail a deploy.
- When moving a page or renaming a heading, update every link to it; a
redirect in `src/data/redirects.ts` does not satisfy the check.
- Link to this site with relative paths (`/admin/config/site-config`), never
`https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`.
- To also probe the external links you added:

```sh
npm run check -- links --check-anchors --check-self-links \
--check-external --diff <(git diff -U0 origin/main)
```

The previous **Langbase** / `baseai` chatbot integration has been fully removed (packages, components, API routes, `baseai/` memory config, and the `pnpm sync` script).

## Important Notes

- **Assistant ID**: The `runllm-assistant-id` is currently set to "YOUR_ASSISTANT_ID" and needs to be updated with the actual Sourcegraph runLLM assistant ID
- **Deployment**: After updating the assistant ID, add the deployment URL to the runLLM dashboard
- **Styling**: The widget inherits the site's theme and uses the Sourcegraph brand color (#FF5543)
146 changes: 96 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,70 @@
# Sourcegraph Docs

> [!IMPORTANT]
> For support, please reach out to your account team or contact [support@sourcegraph.com](mailto:support@sourcegraph.com)
> For support, please reach out to your account team or contact
> [support@sourcegraph.com](mailto:support@sourcegraph.com)

Welcome to the Sourcegraph documentation! We're excited to have you contribute to our docs. Our docs tech stack is powered by Next.js, TailwindCSS and deployed on Vercel. This guide will walk you through the process of contributing to our documentation.
Welcome to the Sourcegraph documentation! We're excited to have you contribute
to our docs. Our docs tech stack is powered by Next.js, TailwindCSS and deployed
on Vercel. This guide will walk you through the process of contributing to our
documentation.

## Get started

To get started with this template, clone this repository to your local machine using the following command:
To get started with this template, clone this repository to your local machine
using the following command:

```sh
git clone https://github.com/sourcegraph/docs.git docs
```

Navigate to the project directory by typing the following command in your terminal:
Navigate to the project directory by typing the following command in your
terminal:

```sh
cd docs
```

Before the dependencies are installed make sure your local machine has the following versions of `node` and `pnpm` installed:
Before the dependencies are installed make sure your local machine has the
following versions of `node` and `pnpm` installed:

- node: `v20.19.6`
- pnpm: `10.25.0`
- node: `v20.19.6`
- pnpm: `10.25.0`

**Note**: If you have `mise` available you can install the above versions for only this repository by running the following command from your terminal in the root folder:
**Note**: If you have `mise` available you can install the above versions for
only this repository by running the following command from your terminal in the
root folder:

```sh
mise install
```

Now that the base requirements of the project have been satisfied, we can install the required dependencies to run the development server!
Now that the base requirements of the project have been satisfied, we can
install the required dependencies to run the development server!

```sh
pnpm install
```

Spell checking is not part of the project dependencies. To run it locally: `npx cspell@10 --no-progress --dot '**/*'`
Spell checking is not part of the project dependencies. To run it locally:
`npx cspell@10 --no-progress --dot '**/*'`

Next, run the development server:

```sh
pnpm run dev
```

Finally, open [`http://localhost:3000`](http://localhost:3000) in your browser to view the website.
Finally, open [`http://localhost:3000`](http://localhost:3000) in your browser
to view the website.

## Writing and contributing to Sourcegraph Docs

### (Easy) Using GitHub to edit existing files

You can easily update existing docs pages using [GitHub's file editor](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files). All you need to do is:
You can easily update existing docs pages using
[GitHub's file editor](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files).
All you need to do is:

1. Find the corresponding `.mdx` file in the [folder structure](#folder-structure).
2. Click the pencil icon to open the file editor.
Expand All @@ -59,33 +73,42 @@ You can easily update existing docs pages using [GitHub's file editor](https://d
5. Provide a Commit message and an Extended description.
6. Click on the green "Propose changes" button to create a PR.
7. Add a PR reviewer to the Reviewers panel by clicking on the gear icon.
8. Tag `@maedahbatool` in the `#docs` Slack channel and link to your PR to get a quick review.
> NOTE: "Edit from GitHub" is generally recommended for text-based edits. For more structural-based contributions like adding React components and code blocks, it's always better to go with a local setup. This way, you can preview changes before you commit.
8. Tag `@maedahbatool` in the `#docs` Slack channel and link to your PR to get
a quick review.
> NOTE: "Edit from GitHub" is generally recommended for text-based edits.
> For more structural-based contributions like adding React components and
> code blocks, it's always better to go with a local setup. This way, you
> can preview changes before you commit.

### (Advanced) Local dev environment

To add new or update existing docs content. Create a new branch and checkout by via:
To add new or update existing docs content. Create a new branch and checkout by
via:

```sh
git switch -c BRANCH_NAME_HERE
```

### Folder structure

The folder structure is exactly the same here. All the docs reside within the `/docs` folder. Here you'll find separate folders for every docs section like `cody`, `code-search`, `cli`, etc.
The folder structure is exactly the same here. All the docs reside within the
`/docs` folder. Here you'll find separate folders for every docs section like
`cody`, `code-search`, `cli`, etc.

- Navigate to the relevant relevant section for your contribution
- If you're adding a new page, create a new MDX file (e.g., `my-new-page.mdx`) in the appropriate folder
- Navigate to the relevant section for your contribution
- If you're adding a new page, create a new MDX file (e.g., `my-new-page.mdx`)
in the appropriate folder

### Frontmatter

Each MDX file can include frontmatter at the top of the file to configure page metadata. Here are the supported fields:
Each MDX file can include frontmatter at the top of the file to configure page
metadata. Here are the supported fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | No | The page title |
| `date` | date | No | Last modified date (used in sitemap) |
| `seoPriority` | number | No | SEO priority for sitemap (0.0 to 1.0, default: 0.5) |
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------- |
| `title` | string | No | The page title |
| `date` | date | No | Last modified date (used in sitemap) |
| `seoPriority` | number | No | Sitemap priority 0.0–1.0, default 0.5 |

Example:

Expand All @@ -99,10 +122,11 @@ seoPriority: 0.8

### Using MDX

We use MDX for our documentation, which allows you to seamlessly integrate JSX (React components) within Markdown. Write your content using standard markdown syntax. For example,

```
We use MDX for our documentation, which allows you to seamlessly integrate JSX
(React components) within Markdown. Write your content using standard markdown
syntax. For example,

```md
# This is heading 1

This is an introductory paragraph.
Expand All @@ -122,66 +146,88 @@ This is how you add a [demo-link](https://sourcegraph.com/)

### Including React Components

The only difference with this new stack is its ability to use React components. We have a set of reusable React components located in the `src/components` directory. These components are designed to enhance the user experience and maintain consistency across our documentation.
The only difference with this new stack is its ability to use React components.
We have a set of reusable React components located in the `src/components`
directory. These components are designed to enhance the user experience and
maintain consistency across our documentation.

For example the cards layout appears by using the `<Callout>` component that can add `note`, `info`, or `warning` notices in docs.
For example the cards layout appears by using the `<Callout>` component that
can add `note`, `info`, or `warning` notices in docs.

![](https://storage.googleapis.com/sourcegraph-assets/Docs/CleanShot%202023-12-12%20at%2012.00.29%402x.png)
![Callout components rendered in the docs](https://storage.googleapis.com/sourcegraph-assets/Docs/CleanShot%202023-12-12%20at%2012.00.29%402x.png)

You can use this component within your content as follows:

```js
<Callout type="note">This feature is currently in Beta for all users.</Callout>
```

This snippet creates a single `<QuickLink>` titled as "Get Cody". You can add as many cards you want while filling out all the relevant details.
This snippet creates a single `<QuickLink>` titled as "Get Cody". You can add
as many cards you want while filling out all the relevant details.

Here are the list of all the supported components we have:

- `<QuickLinks>`
- `<ProductLinks>`
- `<LinkCards>`
- `<Callout>`
- `<QuickLinks>`
- `<ProductLinks>`
- `<LinkCards>`
- `<Callout>`

For a better docs experience, we'll continue adding more components in the future.
For a better docs experience, we'll continue adding more components in the
future.

### Adding a link

To add a `link` to any docs page, use the following routing syntax: `[Link text](path-to-link)`.
To add a `link` to any docs page, use the following routing syntax:
`[Link text](path-to-link)`.

- Do not include `/docs` in the link paths. The base URL will be `sourcegraph.com/docs`
- There should be **no file extension** in the path name
- Do not include `/docs` in the link paths. The base URL will be
`sourcegraph.com/docs`
- There should be **no file extension** in the path name

For example, if you want to link to the Cody Quickstart somewhere in the Code Search docs, you should use:
For example, if you want to link to the Cody Quickstart somewhere in the Code
Search docs, you should use:

```markdown
- This is a link to [Cody Quickstart](/cody/quickstart) in Code Search docs
- This is a way to hash-link to [Cody for VSCode installation](/cody/clients/install-vscode#verifying-the-installation) in Code Search docs
- Link to the [Cody Quickstart](/cody/quickstart)
- Hash-link to a heading:
[Verify the install](/cody/clients/install-vscode#verifying-the-installation)
```

### Adding media assets (images, videos and gifs)

You can upload images, videos and gifs to Sourcegraph docs. For a more detailed instructions visit [this page](https://www.notion.so/sourcegraph/How-to-host-blog-assets-using-GCP-file-storage-a2cae02bd0c74166a12eaff5062c41ad).
You can upload images, videos and gifs to Sourcegraph docs. For a more detailed
instructions visit
[this page](https://www.notion.so/sourcegraph/How-to-host-blog-assets-using-GCP-file-storage-a2cae02bd0c74166a12eaff5062c41ad).

> Note: Make sure to use [ImageOptim.app](https://imageoptim.com/mac) to reduce the size of the images before uploading, since large images degrade page loading speed.
> Note: Make sure to use [ImageOptim.app](https://imageoptim.com/mac) to reduce
> the size of the images before uploading, since large images degrade page
> loading speed.

## Previewing Changes

### Locally

As you make changes to the documentation, the development server will automatically update. Review your changes by navigating to `http://localhost:3000` in your browser.
As you make changes to the documentation, the development server will
automatically update. Review your changes by navigating to
`http://localhost:3000` in your browser.

### Previewing Vercel Deployments

When you open a PR Vercel deploys and provides you with a preview deployment link. To view your deployment, click the **Visit Preview** link from Vercel's deployment panel in your PRs and you get a preview of your docs
When you open a PR Vercel deploys and provides you with a preview deployment
link. To view your deployment, click the **Visit Preview** link from Vercel's
deployment panel in your PRs and you get a preview of your docs

![CleanShot 2024-11-05 at 10 11 29@2x](https://github.com/user-attachments/assets/b0911e2e-95a7-4f56-b2ff-b659d13077d8)
![Vercel deployment panel on a PR](https://github.com/user-attachments/assets/b0911e2e-95a7-4f56-b2ff-b659d13077d8)

## Submitting your Contribution

Once you're satisfied with your changes, follow these steps:

- Commit your changes
- Create a pull request to the [Sourcegraph documentation repository](https://github.com/sourcegraph/docs), and tag the appropriate reviewers.
- Commit your changes
- Create a pull request to the
[Sourcegraph documentation repository](https://github.com/sourcegraph/docs),
and tag the appropriate reviewers.

Thank you for contributing to Sourcegraph documentation! Your efforts help us provide top-notch learning experiences for our users. If you have any questions or need assistance, feel free to reach out.
Thank you for contributing to Sourcegraph documentation! Your efforts help us
provide top-notch learning experiences for our users. If you have any questions
or need assistance, feel free to reach out.
Loading