Skip to content

Add link element #4736

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

Draft
Duncanma wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add link element #4736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88098ed
Add new <link> element pointing at markdown content
Duncanma Jun 17, 2026
8757efe
removing a stale comment
Duncanma Jun 17, 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
3 changes: 2 additions & 1 deletion src/components/LLMActions/LLMActions.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import { FaRegCopy, FaCheck, FaMarkdown, FaExternalLinkAlt, FaChevronDown, FaChevronUp } from 'react-icons/fa';
import { SiOpenai, SiClaude } from 'react-icons/si';
import styles from './LLMActions.module.css';
import { getMarkdownPath } from './markdownPath';

export default function LLMActions() {
const [copied, setCopied] = useState(false);
Expand All @@ -22,7 +23,7 @@ export default function LLMActions() {
// that build output rather than the raw MDX source.
// NOTE: the .md files only exist after `yarn build`; under `yarn start` (dev
// server) these requests will 404. Verify locally with `yarn build && yarn serve`.
const mdPath = `${permalink.replace(/\/$/, '')}.md`;
const mdPath = getMarkdownPath(permalink);
const mdUrl = `${siteConfig.url}${mdPath}`;

const prompt = `Read ${mdUrl} and answer questions about the content.`;
Expand Down
34 changes: 34 additions & 0 deletions src/components/LLMActions/MarkdownAlternateLink.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import React from 'react';
import Head from '@docusaurus/Head';
import { useDoc } from '@docusaurus/plugin-content-docs/client';
import { getMarkdownPath } from './markdownPath';

/**
* Emits a per-page <link rel="alternate" type="text/markdown"> into the page
* <head>, pointing at the generated clean Markdown (<permalink>.md). This lets
* crawlers and LLMs discover the Markdown rendition without constructing the URL.
*
* Rendered server-side into the static HTML by the swizzled DocItem/Content.
* Skipped on pages with no Markdown counterpart (llm_exclude), matching the
* markdown-pages plugin and LLMActions. See MARKDOWN_PIPELINE.md.
*/
export default function MarkdownAlternateLink(): JSX.Element | null {
const { metadata, frontMatter } = useDoc();

if (!metadata.permalink || frontMatter.llm_exclude) {
return null;
}

const href = getMarkdownPath(metadata.permalink);

return (
<Head>
<link
rel="alternate"
type="text/markdown"
href={href}
title={metadata.title}
/>
</Head>
);
}
11 changes: 11 additions & 0 deletions src/components/LLMActions/markdownPath.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
/**
* Site-relative path to the generated clean Markdown for a doc permalink.
*
* The markdown-pages plugin writes each page to `<permalink>.md` at build time
* (see MARKDOWN_PIPELINE.md). Shared by LLMActions (Copy / View as Markdown) and
* MarkdownAlternateLink (the <link rel="alternate"> head tag) so the convention
* lives in one place.
*/
export function getMarkdownPath(permalink: string): string {
return `${permalink.replace(/\/$/, '')}.md`;
}
2 changes: 2 additions & 0 deletions src/theme/DocItem/Content/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import MDXContent from '@theme/MDXContent';
import type { Props } from '@theme/DocItem/Content';

import LLMActions from '@site/src/components/LLMActions/LLMActions';
import MarkdownAlternateLink from '@site/src/components/LLMActions/MarkdownAlternateLink';
import styles from './styles.module.css';

/**
Expand All @@ -28,6 +29,7 @@ export default function DocItemContent({ children }: Props): JSX.Element {

return (
<div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
<MarkdownAlternateLink />
{syntheticTitle && (
<header className={styles.header}>
<Heading as="h1">{syntheticTitle}</Heading>
Expand Down