From 45019108755d6d569d221a7abe558367b760004e Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Thu, 10 Sep 2026 23:42:02 -0600 Subject: [PATCH 1/4] docs: remove build lint warnings Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- pnpm-lock.yaml | 17 ++++++----------- src/app/api/og/[...path]/route.tsx | 3 ++- src/components/ContentTabs.jsx | 7 +------ src/components/Logo.tsx | 2 ++ src/components/mdx/LinkCards.tsx | 1 + src/components/mdx/ProductCards.tsx | 1 + src/components/mdx/ZoomableImage.tsx | 2 ++ 7 files changed, 15 insertions(+), 18 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c71d9b930..eb0c7173b 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1837,8 +1837,8 @@ packages: resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==} engines: {node: 18 || 20 || >=22} - baseline-browser-mapping@2.11.21: - resolution: {integrity: sha512-uh8vpY/1/YyFkunIDFH/12p7/7VdPKA1hejMVEbdkEaWnUz0Hesvx5EbiU6XxjyHZIOju+ZMbQJkRh+es3/spQ==} + baseline-browser-mapping@2.11.22: + resolution: {integrity: sha512-pWc4w51fBFd7mav43/zKRC+RI6f4yfzQoVlfvE8dECePyfkn1bzLp01Fj0QACcyCZyFhiEMyD2qScfKRWgWibA==} engines: {node: '>=6.0.0'} hasBin: true @@ -1906,9 +1906,6 @@ packages: resolution: {integrity: sha512-DLIsRzJVBQu72meAKPkWQOLcujdXT32hwdfnkI1frSiSRMK1MofjKHf+MEx0SB6fjEFXL8fBDv1dKymBlOp4Qw==} engines: {node: '>=0.10.0'} - caniuse-lite@1.0.30001769: - resolution: {integrity: sha512-BCfFL1sHijQlBGWBMuJyhZUhzo7wer5sVj9hqekB/7xn0Ypy+pER/edCYQm4exbXj4WiySGp40P8UuTh6w1srg==} - caniuse-lite@1.0.30001810: resolution: {integrity: sha512-TITQPUkaz+aVk5GL6NhOdwk1aEaNTSDPsGFWrTuhKGtjTF70jL/Oht2W4c6rXUe5fu7Ie19VIahAXHIIiWWNeg==} @@ -6444,7 +6441,7 @@ snapshots: autoprefixer@10.4.24(postcss@8.5.28): dependencies: browserslist: 4.28.9 - caniuse-lite: 1.0.30001769 + caniuse-lite: 1.0.30001810 fraction.js: 5.3.4 picocolors: 1.1.1 postcss: 8.5.28 @@ -6464,7 +6461,7 @@ snapshots: balanced-match@4.0.4: {} - baseline-browser-mapping@2.11.21: {} + baseline-browser-mapping@2.11.22: {} big.js@5.2.2: {} @@ -6489,7 +6486,7 @@ snapshots: browserslist@4.28.9: dependencies: - baseline-browser-mapping: 2.11.21 + baseline-browser-mapping: 2.11.22 caniuse-lite: 1.0.30001810 electron-to-chromium: 1.5.425 node-releases: 2.0.55 @@ -6534,8 +6531,6 @@ snapshots: camelcase@2.1.1: {} - caniuse-lite@1.0.30001769: {} - caniuse-lite@1.0.30001810: {} ccount@2.0.1: {} @@ -9009,7 +9004,7 @@ snapshots: '@next/env': 14.2.35 '@swc/helpers': 0.5.5 busboy: 1.6.0 - caniuse-lite: 1.0.30001769 + caniuse-lite: 1.0.30001810 graceful-fs: 4.2.11 postcss: 8.4.31 react: 18.3.1 diff --git a/src/app/api/og/[...path]/route.tsx b/src/app/api/og/[...path]/route.tsx index da9dbd2ee..701cd9c2d 100644 --- a/src/app/api/og/[...path]/route.tsx +++ b/src/app/api/og/[...path]/route.tsx @@ -42,7 +42,8 @@ export async function GET( }} > {/* Sourcegraph logo */} - + {/* eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text -- Satori requires a native image, and alt text is not rendered. */} + {/* Title */}
{ - updateTabFromURL(); - }, []); - - const updateTabFromURL = () => { - const path = `/${params.slug.join('/')}`; const allPaths = children.map(child => child.props.href) @@ -38,7 +33,7 @@ export function ContentTabs({ children, name }) { console.log('allPaths__', allPaths[0]) } } else setSelectedTab(path) - }; + }, [children, name, params.slug]); if (!onTab) return
{postContent}
diff --git a/src/components/Logo.tsx b/src/components/Logo.tsx index 82eec1921..2acb056e7 100644 --- a/src/components/Logo.tsx +++ b/src/components/Logo.tsx @@ -3,11 +3,13 @@ export function Logo(props: React.ComponentPropsWithoutRef<'svg'>) { return ( <> + {/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */} Sourcegraph Docs + {/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */}
+ {/* eslint-disable-next-line @next/next/no-img-element -- Small MDX icons do not need image optimization. */} {imgAlt}

diff --git a/src/components/mdx/ProductCards.tsx b/src/components/mdx/ProductCards.tsx index ac298fb5e..38f0f7d03 100644 --- a/src/components/mdx/ProductCards.tsx +++ b/src/components/mdx/ProductCards.tsx @@ -28,6 +28,7 @@ export function ProductCard({
+ {/* eslint-disable-next-line @next/next/no-img-element -- Small MDX icons do not need image optimization. */} {imgAlt}

diff --git a/src/components/mdx/ZoomableImage.tsx b/src/components/mdx/ZoomableImage.tsx index eeb8aaa9c..ef395215c 100644 --- a/src/components/mdx/ZoomableImage.tsx +++ b/src/components/mdx/ZoomableImage.tsx @@ -28,6 +28,7 @@ export function ZoomableImage({className, alt, ...props}: ZoomableImageProps) { return ( <> + {/* eslint-disable-next-line @next/next/no-img-element -- MDX image dimensions are unknown. */} {alt} + {/* eslint-disable-next-line @next/next/no-img-element -- MDX image dimensions are unknown. */} {alt} Date: Fri, 11 Sep 2026 05:00:26 -0600 Subject: [PATCH 2/4] Fix README markdownlint findings Wrap prose at 80 columns, run Prettier (single-space list markers, aligned table), add a language to the MDX example fence and alt text to both images, and shorten the two lines that could not wrap. Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- README.md | 146 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 96 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 3323b01e0..061fc979d 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,53 @@ # 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: @@ -44,13 +55,16 @@ Next, run the development server: 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. @@ -59,12 +73,17 @@ 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 @@ -72,20 +91,24 @@ 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: @@ -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. @@ -122,11 +146,15 @@ 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 `` component that can add `note`, `info`, or `warning` notices in docs. +For example the cards layout appears by using the `` 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: @@ -134,54 +162,72 @@ You can use this component within your content as follows: This feature is currently in Beta for all users. ``` -This snippet creates a single `` titled as "Get Cody". You can add as many cards you want while filling out all the relevant details. +This snippet creates a single `` 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: -- `` -- `` -- `` -- `` +- `` +- `` +- `` +- `` -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. From 425dd0ff485467b830c66aba0e60dd91fca13ddc Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Fri, 11 Sep 2026 05:05:51 -0600 Subject: [PATCH 3/4] Fix AGENTS.md markdownlint findings and drop stale runLLM section Wrap the build commands at 80 columns and move the link-check guidance into its own flat list so Prettier and markdownlint agree on indentation. The AI Chat Integration and Important Notes sections described a runLLM widget removed in #1536; replace them with a two-line note. Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- AGENTS.md | 71 +++++++++++++++++++++---------------------------------- 1 file changed, 27 insertions(+), 44 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 580711718..30c530265 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,50 +2,33 @@ ## 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 ` 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 `