OpenGraph attributes Yet another essential feature for websites in modern era.

Changes

9 changed files (+113/-6)

• cli.ts
  • @@ -134,6 +134,7 @@ "logo-image",
    "doc-ext", "lang", "base-url", + "og-image", ], boolean: [ "help",
  • @@ -359,10 +360,14 @@ binary: Deno.readFileSync(siteLogoPath),
    }; } + let isFullBaseURL = false; const baseURL = flags["base-url"] || configFile.output?.baseURL; try { if (baseURL) { - new URL(baseURL, "macana://placeholder"); + const url = new URL(baseURL, "macana://placeholder"); + // If the `baseURL` is valid full URL, it overrides the "macana://placeholder" and + // `protocol` would be one of the given URL. + isFullBaseURL = url.protocol !== "macana:"; } } catch (error) { throw new Error(
  • @@ -371,6 +376,23 @@ { cause: error },
    ); } + let ogImage: { ext: string; data: Uint8Array } | undefined = undefined; + const ogImagePath = flags["og-image"] || + configFile.metadata?.openGraph?.image; + if (ogImagePath) { + log.debug(`metadata.openGraph.image = "${ogImagePath}"`); + if (isFullBaseURL) { + ogImage = { + ext: path.extname(ogImagePath), + data: Deno.readFileSync(ogImagePath), + }; + } else { + log.warn( + "Open Graph image is set but base URL is not full URL: ignoring `metadata.openGraph.image` field.", + ); + } + } + const pageBuilder = new DefaultThemeBuilder({ siteName, copyright,
  • @@ -378,6 +400,9 @@ faviconSvg,
    faviconPng, siteLogo, baseURL, + openGraph: ogImage && { + image: ogImage, + }, }); const documentTree = await treeBuilder.build({
• cli/config.ts
  • @@ -30,6 +30,10 @@
    copyright?: string; logoImage?: string; + + openGraph?: { + image?: string; + }; }; documents?: {
  • @@ -82,6 +86,9 @@ png: fsPathParser,
    }), copyright: parser.string(), logoImage: fsPathParser, + openGraph: parser.object({ + image: fsPathParser, + }), }), documents: parser.object({ defaultLanguage: parser.string({ nonEmpty: true }),
• docs/.macana/config.jsonc
  • @@ -30,7 +30,10 @@ // Just using logo vector image.
    "svg": "../Assets/logo.svg", "png": "../Assets/logo-64x64.png" }, - "logoImage": "../Assets/logo.svg" + "logoImage": "../Assets/logo.svg", + "openGraph": { + "image": "../Assets/opengraph.png" + } }, "markdown": { // Some pages have creation/update date in YAML frontmatter.
• docs/Assets/opengraph.png (new)
• docs/en/References/Config.md
  • @@ -87,6 +87,17 @@
    Path to an image file to use as a website logo. Path needs to be relative and resolved from the config file. + ### `metadata.openGraph.image` + + - Type: `string` (file path) + - CLI: `--og-image <PATH>` option + + Path to an image file to use as an [Open Graph](https://ogp.me/) image (`og:image`). + Path needs to be relative and resolved from the config file. + + Macana sets Open Graph attributes only when the value of [[#`output.baseURL`]] is full URL string. + Path only strings and such are not considered as Open Graph ready base URL. + ## Document options ### `documents.defaultLanguage`
• docs/en/Roadmap.md
  • @@ -1,6 +1,6 @@
    --- createdAt: 2024-04-15T23:00:00+09:00 - updatedAt: 2024-05-26T18:50:00+09:00 + updatedAt: 2024-05-29T15:00:00+09:00 --- ## v1.0
  • @@ -15,7 +15,7 @@ - [ ] Style every tags generated by Markdown
    ## v0.2 - - [ ] Option for OpenGraph attributes + - [x] Option for OpenGraph attributes - [ ] Custom fonts per language - [ ] User provided global CSS - [ ] Headings down levelling option (render `# Foo` as `<h2>Foo</h2>`)
• page_builder/default_theme/context.ts
  • @@ -5,6 +5,7 @@ globalCss: readonly string[];
    faviconSvg?: readonly string[]; faviconPng?: readonly string[]; siteLogo?: readonly string[]; + openGraphImage?: readonly string[]; } export interface BuildContext {
• page_builder/default_theme/mod.ts
  • @@ -127,6 +127,13 @@ /**
    * URL or path to base at. */ baseURL?: URL | string; + + openGraph?: { + image: { + ext: string; + data: Uint8Array; + }; + }; } /**
  • @@ -146,10 +153,18 @@ binary: Uint8Array;
    }; #siteName: string; #baseURL?: URL | string; + #openGraph: DefaultThemeBuilderConstructorParameters["openGraph"]; constructor( - { copyright, faviconSvg, faviconPng, siteLogo, siteName, baseURL }: - DefaultThemeBuilderConstructorParameters, + { + copyright, + faviconSvg, + faviconPng, + siteLogo, + siteName, + baseURL, + openGraph, + }: DefaultThemeBuilderConstructorParameters, ) { this.#copyright = copyright; this.#faviconPng = faviconPng;
  • @@ -157,6 +172,7 @@ this.#faviconSvg = faviconSvg;
    this.#siteLogo = siteLogo; this.#siteName = siteName; this.#baseURL = baseURL; + this.#openGraph = openGraph; } async build(
  • @@ -233,6 +249,21 @@ assets.siteLogo,
    this.#siteLogo.binary, ); } + } + + const baseURL = this.#baseURL && + new URL(this.#baseURL, "macana://placeholder"); + const isOpenGraphReady = baseURL && baseURL.protocol !== "macana:"; + + if (isOpenGraphReady && this.#openGraph) { + assets.openGraphImage = [ + ".assets", + `opengraph${this.#openGraph.image.ext}`, + ]; + await fileSystemWriter.write( + assets.openGraphImage, + this.#openGraph.image.data, + ); } const defaultPage = this.#resolveURL([
• page_builder/default_theme/pages/template.tsx
  • @@ -46,6 +46,35 @@ type="image/png"
    href={resolveURL(assets.faviconPng)} /> )} + {assets.openGraphImage && ( + h(null, [ + <meta name="og:title" content={document.metadata.title} />, + <meta name="og:type" content="article" />, + <meta + name="og:image" + content={resolveURL(assets.openGraphImage)} + />, + <meta name="og:url" content={resolveURL([...document.path, ""])} />, + document.metadata.description && ( + <meta + name="og:description" + content={document.metadata.description} + /> + ), + document.metadata.createdAt && ( + <meta + name="article:published_time" + content={document.metadata.createdAt.toISOString()} + /> + ), + document.metadata.updatedAt && ( + <meta + name="article:modified_time" + content={document.metadata.updatedAt.toISOString()} + /> + ), + ]) + )} </head> {h( "body",