From 6e27a5fdc21276cad26cd50e16a2709a40a7cbac Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Sat, 23 Jul 2022 17:23:15 -0500 Subject: [PATCH] Rename Markdown util `getHeaders()` to `getHeadings()` (#4031) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Renamed getHeaders() to getHeadings(), according to RFC #208. * chore: update changeset * fix: expose MarkdownHeading type from `astro` Co-authored-by: Félix Sanz Co-authored-by: Nate Moore --- .changeset/young-radios-call.md | 6 ++++++ .../components/PageContent/PageContent.astro | 4 ++-- .../components/RightSidebar/MoreMenu.astro | 4 ++-- .../RightSidebar/RightSidebar.astro | 4 ++-- .../RightSidebar/TableOfContents.tsx | 16 +++++++-------- examples/docs/src/styles/index.css | 20 +++++++++---------- packages/astro/env.d.ts | 4 +++- packages/astro/src/@types/astro.ts | 14 +++++++++++-- .../astro/src/vite-plugin-markdown/index.ts | 6 +++++- packages/markdown/remark/src/index.ts | 10 +++++----- ...-headers.ts => rehype-collect-headings.ts} | 14 ++++++------- packages/markdown/remark/src/types.ts | 4 ++-- 12 files changed, 64 insertions(+), 42 deletions(-) create mode 100644 .changeset/young-radios-call.md rename packages/markdown/remark/src/{rehype-collect-headers.ts => rehype-collect-headings.ts} (84%) diff --git a/.changeset/young-radios-call.md b/.changeset/young-radios-call.md new file mode 100644 index 000000000..754c363a9 --- /dev/null +++ b/.changeset/young-radios-call.md @@ -0,0 +1,6 @@ +--- +'astro': patch +'@astrojs/markdown-remark': minor +--- + +**BREAKING** Renamed Markdown utility function `getHeaders()` to `getHeadings()`. diff --git a/examples/docs/src/components/PageContent/PageContent.astro b/examples/docs/src/components/PageContent/PageContent.astro index 1d14515c1..11c130b05 100644 --- a/examples/docs/src/components/PageContent/PageContent.astro +++ b/examples/docs/src/components/PageContent/PageContent.astro @@ -4,14 +4,14 @@ import TableOfContents from "../RightSidebar/TableOfContents.tsx"; const { content, githubEditUrl } = Astro.props; const title = content.title; -const headers = content.astro.headers; +const headings = content.astro.headings; ---

{title}

diff --git a/examples/docs/src/components/RightSidebar/MoreMenu.astro b/examples/docs/src/components/RightSidebar/MoreMenu.astro index a78f86d59..9b0e426cf 100644 --- a/examples/docs/src/components/RightSidebar/MoreMenu.astro +++ b/examples/docs/src/components/RightSidebar/MoreMenu.astro @@ -8,7 +8,7 @@ const showMoreSection = CONFIG.COMMUNITY_INVITE_URL || editHref; {showMoreSection &&

More

}
    {editHref && ( -
  • +
  • +
  • - +
    diff --git a/examples/docs/src/components/RightSidebar/TableOfContents.tsx b/examples/docs/src/components/RightSidebar/TableOfContents.tsx index 537508ab4..1d74e820f 100644 --- a/examples/docs/src/components/RightSidebar/TableOfContents.tsx +++ b/examples/docs/src/components/RightSidebar/TableOfContents.tsx @@ -1,11 +1,11 @@ import type { FunctionalComponent } from 'preact'; import { h, Fragment } from 'preact'; import { useState, useEffect, useRef } from 'preact/hooks'; +import { MarkdownHeading } from 'astro'; -const TableOfContents: FunctionalComponent<{ headers: any[] }> = ({ headers = [] }) => { +const TableOfContents: FunctionalComponent<{ headings: MarkdownHeading[] }> = ({ headings = [] }) => { const itemOffsets = useRef([]); const [activeId, setActiveId] = useState(undefined); - useEffect(() => { const getItemOffsets = () => { const titles = document.querySelectorAll('article :is(h1, h2, h3, h4)'); @@ -27,18 +27,18 @@ const TableOfContents: FunctionalComponent<{ headers: any[] }> = ({ headers = [] <>

    On this page

     diff --git a/examples/docs/src/styles/index.css b/examples/docs/src/styles/index.css index 971ccf9e5..2a735decf 100644 --- a/examples/docs/src/styles/index.css +++ b/examples/docs/src/styles/index.css @@ -311,42 +311,42 @@ h2.heading { margin-bottom: 0.5rem; } -.header-link { +.heading-link { font-size: 1rem; padding: 0.1rem 0 0.1rem 1rem; border-left: 4px solid var(--theme-divider); } -.header-link:hover, -.header-link:focus { +.heading-link:hover, +.heading-link:focus { border-left-color: var(--theme-accent); color: var(--theme-accent); } -.header-link:focus-within { +.heading-link:focus-within { color: var(--theme-text-light); border-left-color: hsla(var(--color-gray-40), 1); } -.header-link svg { +.heading-link svg { opacity: 0.6; } -.header-link:hover svg { +.heading-link:hover svg { opacity: 0.8; } -.header-link a { +.heading-link a { display: inline-flex; gap: 0.5em; width: 100%; padding: 0.15em 0 0.15em 0; } -.header-link.depth-3 { +.heading-link.depth-3 { padding-left: 2rem; } -.header-link.depth-4 { +.heading-link.depth-4 { padding-left: 3rem; } -.header-link a { +.heading-link a { font: inherit; color: inherit; text-decoration: none; diff --git a/packages/astro/env.d.ts b/packages/astro/env.d.ts index 81b4cf140..a018eca20 100644 --- a/packages/astro/env.d.ts +++ b/packages/astro/env.d.ts @@ -18,7 +18,9 @@ declare module '*.md' { export const frontmatter: MD['frontmatter']; export const file: MD['file']; export const url: MD['url']; - export const getHeaders: MD['getHeaders']; + export const getHeadings: MD['getHeadings']; + /** @deprecated Renamed to `getHeadings()` */ + export const getHeaders: () => void; export const Content: MD['Content']; export const rawContent: MD['rawContent']; export const compiledContent: MD['compiledContent']; diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index 6e5068e89..dade40631 100644 --- a/packages/astro/src/@types/astro.ts +++ b/packages/astro/src/@types/astro.ts @@ -1,5 +1,5 @@ import type { - MarkdownHeader, + MarkdownHeading, MarkdownMetadata, MarkdownRenderingResult, RehypePlugins, @@ -16,6 +16,14 @@ import type { AstroConfigSchema } from '../core/config'; import type { ViteConfigWithSSR } from '../core/create-vite'; import type { AstroComponentFactory, Metadata } from '../runtime/server'; export type { SSRManifest } from '../core/app/types'; +export type { + MarkdownHeading, + MarkdownMetadata, + MarkdownRenderingResult, + RehypePlugins, + RemarkPlugins, + ShikiConfig, +} from '@astrojs/markdown-remark'; export interface AstroBuiltinProps { 'client:load'?: boolean; @@ -783,7 +791,9 @@ export interface MarkdownInstance> { rawContent(): string; /** Markdown file compiled to valid Astro syntax. Queryable with most HTML parsing libraries */ compiledContent(): Promise; - getHeaders(): Promise; + getHeadings(): Promise; + /** @deprecated Renamed to `getHeadings()` */ + getHeaders(): void; default: () => Promise<{ metadata: MarkdownMetadata; frontmatter: MarkdownContent; diff --git a/packages/astro/src/vite-plugin-markdown/index.ts b/packages/astro/src/vite-plugin-markdown/index.ts index fdd009f8a..8b5c58425 100644 --- a/packages/astro/src/vite-plugin-markdown/index.ts +++ b/packages/astro/src/vite-plugin-markdown/index.ts @@ -123,8 +123,12 @@ export default function markdown({ config }: AstroPluginOptions): Plugin { return load().then((m) => m.default(...args)); } Content.isAstroComponentFactory = true; + export function getHeadings() { + return load().then((m) => m.metadata.headings); + } export function getHeaders() { - return load().then((m) => m.metadata.headers); + console.warn('getHeaders() have been deprecated. Use getHeadings() function instead.'); + return load().then((m) => m.metadata.headings); };`, map: null, }; diff --git a/packages/markdown/remark/src/index.ts b/packages/markdown/remark/src/index.ts index 8748eff2b..4dfd7240f 100644 --- a/packages/markdown/remark/src/index.ts +++ b/packages/markdown/remark/src/index.ts @@ -1,7 +1,7 @@ import type { MarkdownRenderingOptions, MarkdownRenderingResult } from './types'; import { loadPlugins } from './load-plugins.js'; -import createCollectHeaders from './rehype-collect-headers.js'; +import createCollectHeadings from './rehype-collect-headings.js'; import rehypeEscape from './rehype-escape.js'; import rehypeExpressions from './rehype-expressions.js'; import rehypeIslands from './rehype-islands.js'; @@ -41,7 +41,7 @@ export async function renderMarkdown( } = opts; const input = new VFile({ value: content, path: fileURL }); const scopedClassName = opts.$?.scopedClassName; - const { headers, rehypeCollectHeaders } = createCollectHeaders(); + const { headings, rehypeCollectHeadings } = createCollectHeadings(); let parser = unified() .use(markdown) @@ -94,8 +94,8 @@ export async function renderMarkdown( parser .use( isAstroFlavoredMd - ? [rehypeJsx, rehypeExpressions, rehypeEscape, rehypeIslands, rehypeCollectHeaders] - : [rehypeCollectHeaders, rehypeRaw] + ? [rehypeJsx, rehypeExpressions, rehypeEscape, rehypeIslands, rehypeCollectHeadings] + : [rehypeCollectHeadings, rehypeRaw] ) .use(rehypeStringify, { allowDangerousHtml: true }); @@ -113,7 +113,7 @@ export async function renderMarkdown( } return { - metadata: { headers, source: content, html: result.toString() }, + metadata: { headings, source: content, html: result.toString() }, code: result.toString(), }; } diff --git a/packages/markdown/remark/src/rehype-collect-headers.ts b/packages/markdown/remark/src/rehype-collect-headings.ts similarity index 84% rename from packages/markdown/remark/src/rehype-collect-headers.ts rename to packages/markdown/remark/src/rehype-collect-headings.ts index 50a9c5da1..b42ed9030 100644 --- a/packages/markdown/remark/src/rehype-collect-headers.ts +++ b/packages/markdown/remark/src/rehype-collect-headings.ts @@ -2,13 +2,13 @@ import Slugger from 'github-slugger'; import { toHtml } from 'hast-util-to-html'; import { visit } from 'unist-util-visit'; -import type { MarkdownHeader, RehypePlugin } from './types.js'; +import type { MarkdownHeading, RehypePlugin } from './types.js'; -export default function createCollectHeaders() { - const headers: MarkdownHeader[] = []; +export default function createCollectHeadings() { + const headings: MarkdownHeading[] = []; const slugger = new Slugger(); - function rehypeCollectHeaders(): ReturnType { + function rehypeCollectHeadings(): ReturnType { return function (tree) { visit(tree, (node) => { if (node.type !== 'element') return; @@ -61,13 +61,13 @@ export default function createCollectHeaders() { } } - headers.push({ depth, slug: node.properties.id, text }); + headings.push({ depth, slug: node.properties.id, text }); }); }; } return { - headers, - rehypeCollectHeaders, + headings, + rehypeCollectHeadings, }; } diff --git a/packages/markdown/remark/src/types.ts b/packages/markdown/remark/src/types.ts index 0a72edf0c..9d09ef294 100644 --- a/packages/markdown/remark/src/types.ts +++ b/packages/markdown/remark/src/types.ts @@ -44,14 +44,14 @@ export interface MarkdownRenderingOptions extends AstroMarkdownOptions { isAstroFlavoredMd?: boolean; } -export interface MarkdownHeader { +export interface MarkdownHeading { depth: number; slug: string; text: string; } export interface MarkdownMetadata { - headers: MarkdownHeader[]; + headings: MarkdownHeading[]; source: string; html: string; }