2 |
5 |
6 |
15 |
16 | ## Example
17 |
18 | Run the docs locally using [pnpm](https://pnpm.io):
19 |
20 | ```shell
21 | pnpm run dev
22 | ```
23 |
24 | ## License
25 |
26 | Licensed under the MIT License, Copyright © HiDeoo.
27 |
28 | See [LICENSE](https://github.com/HiDeoo/starlight-heading-badges/blob/main/LICENSE) for more information.
29 |
--------------------------------------------------------------------------------
/packages/starlight-heading-badges/index.ts:
--------------------------------------------------------------------------------
1 | import type { StarlightPlugin } from '@astrojs/starlight/types'
2 |
3 | import { starlightHeadingBadgesIntegration } from './libs/integration'
4 | import { overrideComponents } from './libs/plugin'
5 |
6 | export default function starlightHeadingBadgesPlugin(): StarlightPlugin {
7 | return {
8 | name: 'starlight-heading-badges-plugin',
9 | hooks: {
10 | 'config:setup'({ addIntegration, config: starlightConfig, logger, updateConfig }) {
11 | addIntegration(starlightHeadingBadgesIntegration())
12 |
13 | updateConfig({
14 | components: overrideComponents(
15 | starlightConfig,
16 | [
17 | { name: 'MobileTableOfContents', fallback: 'HeadingBadgesMobileTableOfContents' },
18 | { name: 'TableOfContents', fallback: 'HeadingBadgesTableOfContents' },
19 | ],
20 | logger,
21 | ),
22 | customCss: [...(starlightConfig.customCss ?? []), 'starlight-heading-badges/styles.css'],
23 | })
24 | },
25 | },
26 | }
27 | }
28 |
--------------------------------------------------------------------------------
/packages/starlight-heading-badges/tests/fixtures/TestPage.ts:
--------------------------------------------------------------------------------
1 | import type { Page } from '@playwright/test'
2 |
3 | import type { TestType } from '../test'
4 |
5 | export class TestPage {
6 | expectedHeadings = [
7 | { text: 'A heading', id: 'a-heading' },
8 | { text: 'Default badge', id: 'default-badge' },
9 | { text: 'A duplicated heading', id: 'a-duplicated-heading' },
10 | { text: 'A duplicated heading', id: 'a-duplicated-heading-1' },
11 | { text: 'Variant badge', id: 'variant-badge' },
12 | { text: 'Non-ToC', id: 'non-toc' },
13 | { text: 'Badge with a space', id: 'badge-with-a-space' },
14 | { text: 'Badge with multiple spaces', id: 'badge-with-multiple-spaces' },
15 | { text: 'Multiple badges', id: 'multiple-badges' },
16 | ]
17 |
18 | expectedCustomHeadings = [
19 | { text: 'Heading with custom ID', id: 'custom1' },
20 | { text: 'Heading with custom ID and a badge', id: 'custom2' },
21 | ]
22 |
23 | constructor(public readonly page: Page) {}
24 |
25 | goto(type: TestType) {
26 | return this.page.goto(`/tests/test-${type}/`)
27 | }
28 | }
29 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2024-present, HiDeoo
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/packages/starlight-heading-badges/libs/plugin.ts:
--------------------------------------------------------------------------------
1 | import type { HookParameters } from '@astrojs/starlight/types'
2 | import type { AstroIntegrationLogger } from 'astro'
3 |
4 | export function overrideComponents(
5 | starlightConfig: StarlightUserConfig,
6 | overrides: ComponentOverride[],
7 | logger: AstroIntegrationLogger,
8 | ): StarlightUserConfig['components'] {
9 | const components = { ...starlightConfig.components }
10 |
11 | for (const { name, fallback } of overrides) {
12 | if (starlightConfig.components?.[name]) {
13 | logger.warn(`A \`<${name}>\` component override is already defined in your Starlight configuration.`)
14 | logger.warn(
15 | `To use \`starlight-heading-badges\`, either remove this override or manually render the content from \`starlight-heading-badges/components/${fallback}.astro\`.`,
16 | )
17 | continue
18 | }
19 | components[name] = `starlight-heading-badges/overrides/${name}.astro`
20 | }
21 |
22 | return components
23 | }
24 |
25 | interface ComponentOverride {
26 | name: keyof NonNullablestarlight-heading-badges 🔖
3 |Starlight plugin to add badges to your Markdown and MDX headings.
4 |
9 |
2 |
10 |
11 |
20 |
21 | ## Getting Started
22 |
23 | Want to get started immediately? Check out the [getting started guide](https://starlight-heading-badges.vercel.app/getting-started/) or check out the [demo](https://starlight-heading-badges.vercel.app/demo/) to see the theme in action.
24 |
25 | ## License
26 |
27 | Licensed under the MIT License, Copyright © HiDeoo.
28 |
29 | See [LICENSE](https://github.com/HiDeoo/starlight-heading-badges/blob/main/LICENSE) for more information.
30 |
--------------------------------------------------------------------------------
/packages/starlight-heading-badges/libs/rehype.ts:
--------------------------------------------------------------------------------
1 | import 'mdast-util-directive'
2 |
3 | import type { ElementContent, Root } from 'hast'
4 | import { CONTINUE, SKIP, visit } from 'unist-util-visit'
5 |
6 | import { deserializeBadges, type Badge } from './badge'
7 |
8 | export function rehypeStarlightHeadingBadges() {
9 | return function transformer(tree: Root) {
10 | visit(tree, (node, index, parent) => {
11 | if (node.type === 'text') {
12 | if (index === undefined || !parent) return CONTINUE
13 |
14 | const badges = deserializeBadges(node.value)
15 | if (badges.length === 0) return SKIP
16 |
17 | for (const badge of badges.reverse()) {
18 | if (badge.heading) {
19 | node.value = badge.heading
20 | parent.children.splice(index + 1, 0, ...createBadgeNode(badge))
21 | } else {
22 | parent.children.splice(index, 1, ...createBadgeNode(badge))
23 | }
24 | }
25 |
26 | return SKIP
27 | }
28 |
29 | return CONTINUE
30 | })
31 | }
32 | }
33 |
34 | function createBadgeNode(badge: Badge): ElementContent[] {
35 | return [
36 | {
37 | type: 'element',
38 | tagName: 'span',
39 | properties: {
40 | 'data-shb-badge': '',
41 | 'data-shb-badge-variant': badge.variant,
42 | },
43 | children: [{ type: 'text', value: badge.text }],
44 | },
45 | {
46 | type: 'text',
47 | value: ' ',
48 | },
49 | ]
50 | }
51 |
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
1 | name: release
2 |
3 | permissions: {}
4 |
5 | on:
6 | push:
7 | branches:
8 | - main
9 |
10 | jobs:
11 | changeset:
12 | name: Changeset
13 | if: ${{ github.repository_owner == 'hideoo' }}
14 | runs-on: ubuntu-latest
15 | permissions:
16 | contents: write
17 | id-token: write
18 | pull-requests: write
19 | steps:
20 | - name: Checkout
21 | uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
22 | with:
23 | fetch-depth: 0
24 | persist-credentials: false
25 |
26 | - name: Install pnpm
27 | uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
28 |
29 | - name: Install Node.js
30 | uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
31 | with:
32 | node-version: 24
33 | package-manager-cache: false
34 |
35 | - name: Install dependencies
36 | run: pnpm install
37 |
38 | - name: Create Release Pull Request or Publish
39 | uses: changesets/action@e0145edc7d9d8679003495b11f87bd8ef63c0cba # v1.5.3
40 | with:
41 | version: pnpm run version
42 | publish: pnpm changeset publish
43 | commit: 'ci: release'
44 | title: 'ci: release'
45 | env:
46 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
47 | NPM_TOKEN: '' # https://github.com/changesets/changesets/issues/1152#issuecomment-3190884868
48 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "starlight-heading-badges-monorepo",
3 | "version": "0.3.0",
4 | "license": "MIT",
5 | "description": "Starlight plugin to add badges to your Markdown and MDX headings.",
6 | "author": "HiDeoo starlight-heading-badges 🔖
3 |Starlight plugin to add badges to your Markdown and MDX headings.
4 |
5 |
6 | 
7 |
8 |
-
25 | {
26 | toc.map((heading) => (
27 |
-
28 |
29 |
30 | 31 | {heading.children.length > 0 && } 32 |
33 | ))
34 | }
35 |