VS Code extension
Find component source, complete props and frontmatter, and format markup on save.
diff --git a/frontend/purestack.studio/guides/links.mdx b/frontend/purestack.studio/guides/links.mdx new file mode 100644 index 00000000..97619c58 --- /dev/null +++ b/frontend/purestack.studio/guides/links.mdx @@ -0,0 +1,124 @@ +--- +title: Links +description: Link to pages, sections, and other sites. Write links relative to your file, and every build checks that they still work. +template: doc +layout: + showNav: true + showToc: true + showFooter: true +nav: + order: 16 + icon: tabler:link +--- + +# Links + +Write a link the way you see your files. PureStack turns it into the right page address and checks it every time the site builds, so a renamed or deleted page never leaves a broken link behind. + +## Link to another page + +Start from the file you are writing in, just like in your editor's file tree. Take this content folder: + +```text +index.mdx +guides/ + index.mdx + semantic-tones.mdx + themes.mdx + components/ + index.mdx + buttons.mdx +``` + +From `guides/semantic-tones.mdx`, these links work: + +| Write | Opens | +| --- | --- | +| `[Themes](./themes)` | `/guides/themes/`, a page in the same folder | +| `[Buttons](./components/buttons)` | `/guides/components/buttons/`, a page in a subfolder | +| `[Components](./components/)` | `/guides/components/`, the main page of a subfolder | +| `[All guides](./)` | `/guides/`, the main page of this folder | +| `[Home](../)` | `/`, the main page one folder up | + +The file extension is optional. `./themes` and `./themes.mdx` open the same page. + +A folder's main page is its `index.mdx`, or a file named after the folder, such as `components/components.mdx`. Link to the folder, like `./components/`, and you reach it either way. + +## Jump to a section + +Add `#` and the section name after the page: + +```md +[Create a skin](./themes#create-a-skin) +[Back to the top](#links) +``` + +A section name is its heading in lowercase, with hyphens between the words. The heading "Create a skin" becomes `#create-a-skin`. Try it: [create a skin](./themes#create-a-skin). + +PureStack checks that the page exists, not the section, so double-check section names after you rename a heading. + +## Links in components + +The same rule works for `href` on any tag, including components and links they build from a value: + +```mdx +One
Two
', 'footer.mdx') + + expect(resolveBody(`One
Two
', + ) + }) + + it('resolves links inside template content', () => { + expect(resolveBody('T')).toBe( + 'T', + ) + }) + + it('leaves code, comments, scripts and look-alike attributes as written', () => { + const html = [ + '<a href="./missing">
',
+ '',
+ '',
+ ].join(''),
+ { basePath: '/docs' },
+ ),
+ ).toBe(
+ [
+ 'Themes',
+ 'Blog',
+ 'Elsewhere',
+ 'Top',
+ '
',
+ '',
+ '',
+ ].join(''),
+ )
+ })
+
+ it('fails with the file that wrote a broken link', () => {
+ expect(() => resolveBody('Typo')).toThrow(
+ 'Content link "./themse" in "guides/semantic-tones.mdx" does not match any page.',
+ )
+ expect(() =>
+ resolveBody(
+ markContentSource('X', 'guides/header.mdx'),
+ ),
+ ).toThrow('Content link "./missing" in "guides/header.mdx"')
+ })
+})
diff --git a/packages/ts-ssg/src/build/page-urls.ts b/packages/ts-ssg/src/build/page-urls.ts
new file mode 100644
index 00000000..4ad22f40
--- /dev/null
+++ b/packages/ts-ssg/src/build/page-urls.ts
@@ -0,0 +1,115 @@
+import type { SiteConfig } from '@purestack/ts-common'
+import { escapeHtml, withBasePath } from '@purestack/ts-util'
+import { type ContentRouteIndex, resolveContentHref } from './content-hrefs'
+
+const CONTENT_SOURCE_TAG = 'purestack-content-source'
+const CONTENT_SOURCE_TAG_NAME = CONTENT_SOURCE_TAG.toUpperCase()
+const PUBLIC_URL_ATTRIBUTES = ['src', 'action', 'poster'] as const
+
+export interface PageUrlOptions {
+ sourceRelPath: string
+ contentRoutes: ContentRouteIndex
+ config: SiteConfig
+}
+
+/**
+ * Marks HTML written in another content file, such as a shared header, so
+ * the links inside it resolve from that file rather than from the page.
+ */
+export function markContentSource(html: string, sourceRelPath: string) {
+ const file = escapeHtml(sourceRelPath.replaceAll('\\', '/'), true)
+ return `<${CONTENT_SOURCE_TAG} file="${file}">${html}`
+}
+
+/**
+ * Finishes every URL in a rendered page. Each `href` resolves from the
+ * content file that wrote it, and root-absolute URLs gain the base path.
+ * Source markers are removed, so the page keeps the markup its files wrote.
+ */
+export function resolvePageUrls(document: Document, options: PageUrlOptions) {
+ visitChildren(document, options.sourceRelPath, options)
+}
+
+function visitChildren(
+ parent: ParentNode,
+ sourceRelPath: string,
+ options: PageUrlOptions,
+) {
+ for (const child of [...parent.childNodes]) {
+ if (!isElement(child)) continue
+ if (child.tagName === CONTENT_SOURCE_TAG_NAME) {
+ visitChildren(child, child.getAttribute('file') ?? sourceRelPath, options)
+ child.replaceWith(...child.childNodes)
+ continue
+ }
+ resolveElementUrls(child, sourceRelPath, options)
+ visitChildren(
+ isTemplate(child) ? child.content : child,
+ sourceRelPath,
+ options,
+ )
+ }
+}
+
+function resolveElementUrls(
+ element: Element,
+ sourceRelPath: string,
+ options: PageUrlOptions,
+) {
+ const { basePath } = options.config
+ const href = element.getAttribute('href')
+ if (href !== null) {
+ const resolved = resolveContentHref(
+ href,
+ sourceRelPath,
+ options.contentRoutes,
+ options.config,
+ )
+ updateAttribute(element, 'href', href, withBasePath(basePath, resolved))
+ }
+ if (!basePath) return
+ for (const name of PUBLIC_URL_ATTRIBUTES) {
+ const value = element.getAttribute(name)
+ if (value !== null) {
+ updateAttribute(element, name, value, withBasePath(basePath, value))
+ }
+ }
+ const srcset = element.getAttribute('srcset')
+ if (srcset !== null) {
+ updateAttribute(
+ element,
+ 'srcset',
+ srcset,
+ withSrcsetBasePath(basePath, srcset),
+ )
+ }
+}
+
+function withSrcsetBasePath(basePath: string, srcset: string) {
+ return srcset
+ .split(',')
+ .map((candidate) => {
+ const url = candidate.trim().split(/\s+/)[0]
+ return url
+ ? candidate.replace(url, withBasePath(basePath, url))
+ : candidate
+ })
+ .join(',')
+}
+
+function updateAttribute(
+ element: Element,
+ name: string,
+ value: string,
+ next: string,
+) {
+ if (next !== value) element.setAttribute(name, next)
+}
+
+function isElement(node: Node): node is Element {
+ return node.nodeType === 1
+}
+
+function isTemplate(element: Element): element is HTMLTemplateElement {
+ return element.tagName === 'TEMPLATE'
+}
diff --git a/packages/ts-ssg/src/build/page.footer.test.ts b/packages/ts-ssg/src/build/page.footer.test.ts
index 4ddb8aaf..c2ec3dcb 100644
--- a/packages/ts-ssg/src/build/page.footer.test.ts
+++ b/packages/ts-ssg/src/build/page.footer.test.ts
@@ -1,15 +1,19 @@
import fs from 'node:fs/promises'
import os from 'node:os'
import path from 'node:path'
+import type { SiteConfig } from '@purestack/ts-common'
import { disableLogger, getLogger, type Logger } from 'logpot'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { resolveSiteConfig } from '../config/config'
+import { discoverContent } from '../discover/content'
import {
type ResolvedContentFile,
+ resolveContentFiles,
resolvePlainContentFile,
} from '../i18n/content'
import { initBuiltinComponents } from '../regor/initBuiltinComponents'
+import { ContentRouteIndex } from './content-hrefs'
import {
renderPageFromFile,
resolveFooterHtmlByDirectory,
@@ -59,14 +63,13 @@ describe('footer hierarchy', () => {
contentDir,
outDir,
})
- const footerHtmlByDir = await resolveFooterHtmlByDirectory(
- config,
- undefined,
- )
+ const contentRoutes = await indexContent(config)
+ const footerHtmlByDir = await resolveFooterHtmlByDirectory({ config })
const rootPage = await renderPageFromFile(
{
config,
+ contentRoutes,
footerHtmlByDir,
},
toContentFile(contentDir, 'index.mdx'),
@@ -76,6 +79,7 @@ describe('footer hierarchy', () => {
const guidePage = await renderPageFromFile(
{
config,
+ contentRoutes,
footerHtmlByDir,
},
toContentFile(contentDir, path.join('guide', 'index.mdx')),
@@ -85,6 +89,7 @@ describe('footer hierarchy', () => {
const guideSubPage = await renderPageFromFile(
{
config,
+ contentRoutes,
footerHtmlByDir,
},
toContentFile(contentDir, path.join('guide', 'sub', 'page.mdx')),
@@ -115,14 +120,13 @@ describe('footer hierarchy', () => {
contentDir,
outDir,
})
- const headerHtmlByDir = await resolveHeaderHtmlByDirectory(
- config,
- undefined,
- )
+ const contentRoutes = await indexContent(config)
+ const headerHtmlByDir = await resolveHeaderHtmlByDirectory({ config })
const page = await renderPageFromFile(
{
config,
+ contentRoutes,
headerHtmlByDir,
resolveScriptPublicPath: () => '/auth-state.m4x9p2.js',
},
@@ -136,8 +140,74 @@ describe('footer hierarchy', () => {
await fs.rm(root, { recursive: true, force: true })
}
})
+
+ it('resolves header links relative to the header file, not the page', async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), 'ts-ssg-'))
+ try {
+ const contentDir = path.join(root, 'content')
+ const outDir = path.join(root, 'out')
+ await writeFile(
+ path.join(contentDir, 'guides', 'header.mdx'),
+ '',
+ )
+ await writeFile(path.join(contentDir, 'index.mdx'), '# Home')
+ await writeFile(path.join(contentDir, 'guides', 'themes.mdx'), '# Themes')
+ await writeFile(
+ path.join(contentDir, 'guides', 'deep', 'page.mdx'),
+ '# Deep',
+ )
+
+ const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
+ const contentRoutes = await indexContent(config)
+ const headerHtmlByDir = await resolveHeaderHtmlByDirectory({ config })
+ const page = await renderPageFromFile(
+ { config, contentRoutes, headerHtmlByDir },
+ toContentFile(contentDir, path.join('guides', 'deep', 'page.mdx')),
+ )
+
+ expect(page.html).toContain('href="/guides/themes/"')
+ expect(page.html).toContain('href="/"')
+ expect(page.html).not.toContain('/guides/deep/themes')
+ expect(page.html).not.toContain('purestack-content-source')
+ } finally {
+ await fs.rm(root, { recursive: true, force: true })
+ }
+ })
+
+ it('fails pages that show a header link matching no page', async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), 'ts-ssg-'))
+ try {
+ const contentDir = path.join(root, 'content')
+ const outDir = path.join(root, 'out')
+ await writeFile(
+ path.join(contentDir, 'header.mdx'),
+ '',
+ )
+ await writeFile(path.join(contentDir, 'index.mdx'), '# Home')
+
+ const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
+ const contentRoutes = await indexContent(config)
+ const headerHtmlByDir = await resolveHeaderHtmlByDirectory({ config })
+ await expect(
+ renderPageFromFile(
+ { config, contentRoutes, headerHtmlByDir },
+ toContentFile(contentDir, 'index.mdx'),
+ ),
+ ).rejects.toThrow(
+ 'Content link "./missing" in "header.mdx" does not match any page.',
+ )
+ } finally {
+ await fs.rm(root, { recursive: true, force: true })
+ }
+ })
})
+async function indexContent(config: SiteConfig) {
+ return new ContentRouteIndex(
+ resolveContentFiles(config, await discoverContent(config.contentDir)),
+ )
+}
+
function toContentFile(
contentDir: string,
relPath: string,
diff --git a/packages/ts-ssg/src/build/page.tabs.test.ts b/packages/ts-ssg/src/build/page.tabs.test.ts
index 4be460de..32263817 100644
--- a/packages/ts-ssg/src/build/page.tabs.test.ts
+++ b/packages/ts-ssg/src/build/page.tabs.test.ts
@@ -14,6 +14,7 @@ import {
type ResolvedContentFile,
resolvePlainContentFile,
} from '../i18n/content'
+import { ContentRouteIndex } from './content-hrefs'
import { renderPageFromFile } from './page'
async function writeFile(filePath: string, contents = '') {
@@ -50,6 +51,7 @@ describe('tabs runtime embedding', () => {
const page = await renderPageFromFile(
{
config,
+ contentRoutes: new ContentRouteIndex([]),
components: {
...defineIconComponents(getSvgIcon),
...defineTabsComponents(),
@@ -89,6 +91,7 @@ embed:
const page = await renderPageFromFile(
{
config,
+ contentRoutes: new ContentRouteIndex([]),
},
toContentFile(contentDir, 'index.mdx'),
)
@@ -122,6 +125,7 @@ embed:
const page = await renderPageFromFile(
{
config,
+ contentRoutes: new ContentRouteIndex([]),
},
toContentFile(contentDir, 'index.mdx'),
)
diff --git a/packages/ts-ssg/src/build/page.test.ts b/packages/ts-ssg/src/build/page.test.ts
index 3bd0ed23..c77f817f 100644
--- a/packages/ts-ssg/src/build/page.test.ts
+++ b/packages/ts-ssg/src/build/page.test.ts
@@ -1,6 +1,7 @@
import fs from 'node:fs/promises'
import os from 'node:os'
import path from 'node:path'
+import type { SiteConfig } from '@purestack/ts-common'
import { disableLogger, getLogger, type Logger } from 'logpot'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { resolveSiteConfig } from '../config/config'
@@ -14,6 +15,7 @@ import {
} from '../i18n/content'
import { buildNavigation } from '../navigation/navigation'
import { initBuiltinComponents } from '../regor/initBuiltinComponents'
+import { ContentRouteIndex } from './content-hrefs'
import { renderPageFromFile } from './page'
async function writeFile(filePath: string, contents = '') {
@@ -46,7 +48,7 @@ describe('page content compilation', () => {
const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'index.md'),
)
@@ -76,7 +78,7 @@ describe('page content compilation', () => {
},
})
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'index.md'),
)
@@ -106,7 +108,7 @@ describe('page content compilation', () => {
},
})
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'index.rmdx'),
)
@@ -129,7 +131,7 @@ describe('page content compilation', () => {
const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'index.md'),
)
@@ -159,7 +161,7 @@ describe('page content compilation', () => {
siteTitle: 'Docs',
})
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'getting-started.md'),
)
@@ -180,7 +182,7 @@ describe('page content compilation', () => {
const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'index.md'),
)
@@ -206,7 +208,7 @@ describe('page content compilation', () => {
const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, 'index.md'),
)
@@ -233,14 +235,113 @@ describe('page content compilation', () => {
path.join(contentDir, 'docs', 'getting-started.md'),
'read and write API',
)
+ await writeFile(
+ path.join(contentDir, 'docs', 'usage', 'reads-and-writes.md'),
+ '# Reads and Writes',
+ )
const config = resolveSiteConfig({ rootDir: root, contentDir, outDir })
const page = await renderPageFromFile(
- { config },
+ { config, contentRoutes: await indexContent(config) },
toContentFile(contentDir, path.join('docs', 'getting-started.md')),
)
- expect(page.bodyHtml).toContain('href="/docs/usage/reads-and-writes/"')
+ expect(page.html).toContain('href="/docs/usage/reads-and-writes/"')
+ } finally {
+ await fs.rm(root, { recursive: true, force: true })
+ }
+ })
+
+ it('resolves every content link after Regor renders the page', async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), 'ts-ssg-page-'))
+ try {
+ const contentDir = path.join(root, 'content')
+ const outDir = path.join(root, 'out')
+ await writeFile(
+ path.join(contentDir, 'guides', 'semantic-tones.mdx'),
+ [
+ '# Semantic tones',
+ '',
+ 'Read [themes](./themes) and [palettes][palette].',
+ '',
+ '[palette]: ./themes#palette',
+ '',
+ 'Home',
+ '',
+ '')
})
- it('rewrites markdown content links when the markdown route is used', async () => {
- const html = compileMarkdown('[Transactions](usage/transactions.md)', {
- sourceRelPath: 'docs/index.md',
- resolveContentHref: resolvePageContentHref,
- }).bodyHtml
-
- expect(html).toContain('href="/docs/usage/transactions/"')
- })
-
it('collects h1, h2, and h3 headings into the page outline', () => {
const source = [
'# Getting Started',
diff --git a/packages/ts-ssg/src/mdx/mdx.test.ts b/packages/ts-ssg/src/mdx/mdx.test.ts
index 19a32444..97adf479 100644
--- a/packages/ts-ssg/src/mdx/mdx.test.ts
+++ b/packages/ts-ssg/src/mdx/mdx.test.ts
@@ -3,7 +3,6 @@ import { defineModalComponents } from '@purestack/ts-components'
import { ensureDomGlobals } from '@purestack/ts-minidom'
import { renderApp } from '@purestack/ts-render'
import { describe, expect, it } from 'vitest'
-import { resolvePageContentHref } from '../build/content-hrefs'
import { resolveSiteConfig } from '../config/config'
import { normalizeFrontmatter } from '../frontmatter/frontmatter'
import { createMdxHighlighter } from './highlight'
@@ -243,28 +242,6 @@ describe('compileMdxToHtml', () => {
expect(html).toContain('Sea ')
})
- it('rewrites markdown content links to routed page URLs', async () => {
- const html = compileMdx('[read and write API](usage/reads-and-writes.md)', {
- sourceRelPath: 'docs/getting-started.md',
- resolveContentHref: resolvePageContentHref,
- }).bodyHtml
-
- expect(html).toContain('href="/docs/usage/reads-and-writes/"')
- expect(html).not.toContain('href="usage/reads-and-writes.md"')
- })
-
- it('rewrites raw HTML content links with the configured link resolver', async () => {
- const html = compileMdx(
- 'Transactions',
- {
- sourceRelPath: 'docs/concepts/storage-engine.md',
- resolveContentHref: resolvePageContentHref,
- },
- ).bodyHtml
-
- expect(html).toContain('href="/docs/usage/transactions/#scope"')
- })
-
it('strips empty paragraphs around template slot content', async () => {
const cleanup = ensureDomGlobals()
const source = [
diff --git a/packages/ts-style/package.json b/packages/ts-style/package.json
index 4d550926..1e068442 100644
--- a/packages/ts-style/package.json
+++ b/packages/ts-style/package.json
@@ -1,6 +1,6 @@
{
"name": "@purestack/ts-style",
- "version": "1.1.1",
+ "version": "1.1.2",
"packageManager": "yarn@4.9.2",
"module": "./dist/ts-style.mjs",
"types": "./dist/ts-style.d.mts",
diff --git a/packages/ts-svg-icons/package.json b/packages/ts-svg-icons/package.json
index d8ba31b4..6fc9f828 100644
--- a/packages/ts-svg-icons/package.json
+++ b/packages/ts-svg-icons/package.json
@@ -1,6 +1,6 @@
{
"name": "@purestack/ts-svg-icons",
- "version": "1.1.1",
+ "version": "1.1.2",
"packageManager": "yarn@4.9.2",
"module": "./dist/ts-svg-icons.mjs",
"types": "./dist/ts-svg-icons.d.mts",
diff --git a/packages/ts-util-node/package.json b/packages/ts-util-node/package.json
index fc8039cf..a0da7da0 100644
--- a/packages/ts-util-node/package.json
+++ b/packages/ts-util-node/package.json
@@ -1,6 +1,6 @@
{
"name": "@purestack/ts-util-node",
- "version": "1.1.1",
+ "version": "1.1.2",
"packageManager": "yarn@4.9.2",
"module": "./dist/ts-util-node.mjs",
"types": "./dist/ts-util-node.d.mts",
diff --git a/packages/ts-util/package.json b/packages/ts-util/package.json
index f25f2841..406ca260 100644
--- a/packages/ts-util/package.json
+++ b/packages/ts-util/package.json
@@ -1,6 +1,6 @@
{
"name": "@purestack/ts-util",
- "version": "1.1.1",
+ "version": "1.1.2",
"packageManager": "yarn@4.9.2",
"module": "./dist/ts-util.mjs",
"types": "./dist/ts-util.d.mts",