Base URL option This is essential for implementing OpenGraph support and 404 pages.

Changes

12 changed files (+90/-44)

• .github/workflows/deploy-docs.yml
  • @@ -51,7 +51,7 @@ with:
    path: ${{ env.DENO_DIR }} key: deploy-${{ hashFiles('deno.lock') }} - name: Build documentation website - run: "deno task build-docs --json" + run: "deno task build-docs --base-url https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/ --json" - name: Upload artifact uses: actions/upload-pages-artifact@v3 with:
• cli.ts
  • @@ -133,6 +133,7 @@ "favicon-svg",
    "logo-image", "doc-ext", "lang", + "base-url", ], boolean: [ "help",
  • @@ -358,12 +359,25 @@ binary: Deno.readFileSync(siteLogoPath),
    }; } + const baseURL = flags["base-url"] || configFile.output?.baseURL; + try { + if (baseURL) { + new URL(baseURL, "macana://placeholder"); + } + } catch (error) { + throw new Error( + `baseURL is not valid URL nor path: ${String(error)}`, + { cause: error }, + ); + } + const pageBuilder = new DefaultThemeBuilder({ siteName, copyright, faviconSvg, faviconPng, siteLogo, + baseURL, }); const documentTree = await treeBuilder.build({
  • @@ -464,6 +478,10 @@ --out <PATH>
    Path to the output directory. Macana creates the target directory if it does not exist at the path. Use slash ("/") for path separator regardless of platform. Corresponding config key is ${p("output.path")} (${t("string")}). + + --base-url <PATH OR URL> + URL or path to base at. + Corresponding config key is ${p("output.baseURL")} (${t("string")}). --copyright <TEXT> Copyright text to display on the generated website.
• cli/config.ts
  • @@ -15,6 +15,8 @@ output?: {
    path?: string; precompress?: boolean; + + baseURL?: string; }; metadata?: {
  • @@ -69,6 +71,7 @@ path: fsPathParser,
    }), output: parser.object({ path: fsPathParser, + baseURL: parser.string({ nonEmpty: true, trim: true }), precompress: parser.boolean, }), metadata: parser.object({
• docs/en/References/Config.md
  • @@ -20,6 +20,17 @@
    Path to the output directory. Path needs to be relative and resolved from the config file. + ### `output.baseURL` + + - Type: `string` (URL or path) + - CLI: `--base-url <URL OR PATH>` option + - Example: `"/foo/"`, `"https://example.com/"` + + Base URL for the generated website. + + Path part needs to end with trailing slash: otherwise the last segment will be omitted. + For example, link for the `Foo.md` under `--base-url /bar/baz` will look like `/bar/Foo/`. + ### `output.precompress` - Type: `boolean`
• docs/en/Roadmap.md
  • @@ -26,7 +26,7 @@ - [x] CLI for opinionated build
    - [x] JSON/JSONC config for CLI - [x] Usage document for CLI - [x] Wikilink internal hash reference - - [ ] Option to set base URL or path + - [x] Option to set base URL or path ## v0.1.1
• page_builder/default_theme/context.ts
  • @@ -35,10 +35,10 @@
    copyright: string; /** - * Resolves the given path as an absolute path from the document root to - * relative path from the current document. + * Returns full URL, absolute path or relative path from the current + * document depends on a base URL. */ - resolvePath(to: readonly string[]): readonly string[]; + resolveURL(path: readonly string[]): string; /** * Copy file to the output directory.
• page_builder/default_theme/from_mdast/embed.tsx
  • @@ -39,7 +39,7 @@ const file = context.documentTree.exchangeToken(node.data.macanaAssetToken);
    context.copyFile(file); - return context.resolvePath(file.path).join("/"); + return context.resolveURL(file.path); } export interface EmbedHandlersParameters {
• page_builder/default_theme/from_mdast/link.tsx
  • @@ -100,9 +100,9 @@ const hash = fragments.length > 0
    ? "#" + document.content.getHash(fragments) : ""; - const path = context.resolvePath([...document.path, ""]); + const path = context.resolveURL([...document.path, ""]); - return path.join("/") + hash; + return path + hash; } export function linkHandlers(
• page_builder/default_theme/mod.ts
  • @@ -76,26 +76,6 @@ ): x is Document<JSONCanvasDocument<Mdast.Nodes>> {
    return x.content.kind === "json_canvas"; } - /** - * @param from - **Directory** to resolve from. - */ - function toRelativePath( - path: readonly string[], - from: readonly string[], - ): readonly string[] { - return [ - ...Array.from({ length: from.length }, () => ".."), - ...path, - ]; - } - - function toRelativePathString( - path: readonly string[], - from: readonly string[], - ): string { - return toRelativePath(path, from).join("/"); - } - interface InnerBuildParameters { item: DocumentDirectory | Document;
  • @@ -142,6 +122,11 @@ siteLogo?: readonly string[] | {
    ext: string; binary: Uint8Array; }; + + /** + * URL or path to base at. + */ + baseURL?: URL | string; } /**
  • @@ -160,9 +145,10 @@ ext: string;
    binary: Uint8Array; }; #siteName: string; + #baseURL?: URL | string; constructor( - { copyright, faviconSvg, faviconPng, siteLogo, siteName }: + { copyright, faviconSvg, faviconPng, siteLogo, siteName, baseURL }: DefaultThemeBuilderConstructorParameters, ) { this.#copyright = copyright;
  • @@ -170,6 +156,7 @@ this.#faviconPng = faviconPng;
    this.#faviconSvg = faviconSvg; this.#siteLogo = siteLogo; this.#siteName = siteName; + this.#baseURL = baseURL; } async build(
  • @@ -248,7 +235,10 @@ );
    } } - const defaultPage = [...documentTree.defaultDocument.path, ""].join("/"); + const defaultPage = this.#resolveURL([ + ...documentTree.defaultDocument.path, + "", + ], []); const redirectHtml = toHtml(indexRedirect({ redirectTo: defaultPage })); await fileSystemWriter.write( ["index.html"],
  • @@ -320,7 +310,7 @@ context.copyFile(file);
    return { ...node, - file: toRelativePathString(file.path, context.document.path), + file: context.resolveURL(file.path), }; }
  • @@ -398,6 +388,8 @@ async #build(
    { item, tree, parentLanguage, pathPrefix = [], buildParameters, assets }: InnerBuildParameters, ): Promise<void> { + const resolveURL = this.#resolveURL; + const { fileSystemWriter } = buildParameters; if ("file" in item) {
  • @@ -410,9 +402,8 @@ language: item.metadata.language || parentLanguage,
    assets, websiteTitle: this.#siteName, copyright: this.#copyright, - resolvePath(to) { - // This page builder transforms path to "Foo/Bar.md" to "Foo/Bar/(index.html)" - return toRelativePath(to, item.path); + resolveURL(to) { + return resolveURL(to, item.path); }, copyFile(file) { writeTasks.push(
  • @@ -464,7 +455,7 @@ );
    return { ...node, - file: toRelativePathString(file.path, item.path), + file: context.resolveURL(file.path), }; }
  • @@ -551,4 +542,27 @@ assets,
    }) )); } + + #resolveURL = (to: readonly string[], from: readonly string[]): string => { + if (!this.#baseURL) { + return [ + ...Array.from({ length: from.length }, () => ".."), + ...to, + ].join("/"); + } + + if (this.#baseURL instanceof URL) { + return new URL(to.join("/"), this.#baseURL).toString(); + } + + const url = new URL( + to.join("/"), + new URL(this.#baseURL, "macana://placeholder"), + ); + if (url.protocol === "macana:") { + return url.pathname; + } + + return url.toString(); + }; }
• page_builder/default_theme/pages/template.tsx
  • @@ -17,7 +17,7 @@ scripts?: readonly string[];
    } export function template({ body, context, scripts = [] }: TemplateProps) { - const { language, document, websiteTitle, assets, resolvePath } = context; + const { language, document, websiteTitle, assets, resolveURL } = context; return ( <html lang={language}>
  • @@ -27,20 +27,20 @@ <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{document.metadata.title} - {websiteTitle}</title> <link rel="stylesheet" - href={resolvePath(assets.globalCss).join("/")} + href={resolveURL(assets.globalCss)} /> {assets.faviconSvg && ( <link rel="icon" type="image/svg+xml" - href={resolvePath(assets.faviconSvg).join("/")} + href={resolveURL(assets.faviconSvg)} /> )} {assets.faviconPng && ( <link rel="icon" type="image/png" - href={resolvePath(assets.faviconPng).join("/")} + href={resolveURL(assets.faviconPng)} /> )} </head>
• page_builder/default_theme/widgets/document_tree.tsx
  • @@ -170,7 +170,7 @@ }
    function node({ currentPath, value, context }: NodeProps) { if ("file" in value) { - const path = context.resolvePath([ + const url = context.resolveURL([ ...value.path.map((segment) => encodeURIComponent(segment)), // For trailing slash "",
  • @@ -183,7 +183,7 @@ return (
    <li lang={value.metadata.language ?? undefined} class={c.document}> <a className={c.link} - href={path.join("/")} + href={url} aria-current={isCurrent ? "page" : undefined} > {value.metadata.title}
• page_builder/default_theme/widgets/layout.tsx
  • @@ -279,7 +279,7 @@ context,
    }: LayoutProps) { const { assets, - resolvePath, + resolveURL, documentTree: { defaultDocument }, websiteTitle, } = context;
  • @@ -302,14 +302,14 @@ />
    <header class={c.appbar}> <a class={c.homeLink} - href={resolvePath([...defaultDocument.path, ""]).join("/")} + href={resolveURL([...defaultDocument.path, ""])} title={defaultDocument.metadata.title} lang={defaultDocument.metadata.language} > {assets.siteLogo && ( <img class={c.logoImage} - src={resolvePath(assets.siteLogo).join("/")} + src={resolveURL(assets.siteLogo)} width={32} height={32} />