astro-d2 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present, HiDeoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+<div align="center">
+  <h1>astro-d2 ✏️</h1>
+  <p>Astro integration and remark plugin to transform D2 Markdown code blocks into diagrams.</p>
+</div>
+
+<div align="center">
+  <a href="https://github.com/HiDeoo/astro-d2/actions/workflows/integration.yml">
+    <img alt="Integration Status" src="https://github.com/HiDeoo/astro-d2/actions/workflows/integration.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/HiDeoo/astro-d2/blob/main/LICENSE">
+    <img alt="License" src="https://badgen.net/github/license/HiDeoo/astro-d2" />
+  </a>
+  <br />
+</div>
+
+## Getting Started
+
+Want to get started immediately? Check out the [getting started guide](https://astro-d2.vercel.app/getting-started/).
+
+## Features
+
+An [Astro](https://astro.build/) integration and [remark](https://remark.js.org/) plugin to transform [D2](https://d2lang.com/) Markdown code blocks into diagrams.
+
+Check out the [examples](https://astro-d2.vercel.app/examples/hello-world/) for previews of some diagrams you can create with D2.
+
+## License
+
+Licensed under the MIT License, Copyright © HiDeoo.
+
+See [LICENSE](https://github.com/HiDeoo/astro-d2/blob/main/LICENSE) for more information.

package/config.ts

@@ -0,0 +1,56 @@
+import { z } from 'astro/zod'
+
+export const AstroD2ConfigSchema = z
+  .object({
+    /**
+     * Defines the layout engine to use to generate the diagrams.
+     *
+     * @default 'dagre'
+     * @see https://d2lang.com/tour/layouts#layout-engines
+     */
+    layout: z.union([z.literal('dagre'), z.literal('elk'), z.literal('tala')]).default('dagre'),
+    /**
+     * The name of the output directory containing the generated diagrams relative to the `public/` directory.
+     *
+     * @default 'd2'
+     */
+    output: z.string().default('d2'),
+    /**
+     * Whether the Astro D2 integration should skip the generation of diagrams.
+     *
+     * This is useful to disable generating diagrams when deploying on platforms that do not have the D2 binary
+     * available. This will require you to build and commit the diagrams before deploying your site.
+     *
+     * @default false
+     */
+    skipGeneration: z.boolean().default(false),
+    /**
+     * The themes to use for the generated diagrams.
+     *
+     * @see https://d2lang.com/tour/themes
+     */
+    theme: z
+      .object({
+        /**
+         * The dark theme to use for the diagrams when the user's system preference is set to dark mode.
+         *
+         * To disable the dark theme and have all diagrams look the same, set this option to `false`.
+         *
+         * @default '200'
+         * @see https://d2lang.com/tour/themes
+         */
+        dark: z.union([z.string(), z.literal(false)]).default('200'),
+        /**
+         * The default theme to use for the diagrams.
+         *
+         * @default '0'
+         * @see https://d2lang.com/tour/themes
+         */
+        default: z.string().default('0'),
+      })
+      .default({}),
+  })
+  .default({})
+
+export type AstroD2UserConfig = z.input<typeof AstroD2ConfigSchema>
+export type AstroD2Config = z.output<typeof AstroD2ConfigSchema>

package/index.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { AstroIntegration } from 'astro'
+
+import { AstroD2ConfigSchema, type AstroD2UserConfig } from './config'
+import { isD2Installed } from './libs/d2'
+import { throwErrorWithHint } from './libs/integration'
+import { remarkAstroD2 } from './libs/remark'
+
+export type { AstroD2UserConfig } from './config'
+
+export default function astroD2Integration(userConfig?: AstroD2UserConfig): AstroIntegration {
+  const parsedConfig = AstroD2ConfigSchema.safeParse(userConfig)
+
+  if (!parsedConfig.success) {
+    throwErrorWithHint(
+      `The provided D2 integration configuration is invalid.\n${parsedConfig.error.issues.map((issue) => issue.message).join('\n')}`,
+    )
+  }
+
+  const config = parsedConfig.data
+
+  return {
+    name: 'astro-d2-integration',
+    hooks: {
+      'astro:config:setup': async ({ command, logger, updateConfig }) => {
+        if (command !== 'build' && command !== 'dev') {
+          return
+        }
+
+        if (config.skipGeneration) {
+          logger.warn("Skipping generation of D2 diagrams as the 'skipGeneration' option is enabled.")
+        } else {
+          if (!(await isD2Installed())) {
+            throwErrorWithHint(
+              'Could not find D2. Please check the installation instructions at https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md',
+            )
+          }
+
+          if (command === 'build') {
+            await fs.rm(path.join('public', config.output), { force: true, recursive: true })
+          }
+        }
+
+        updateConfig({
+          markdown: {
+            remarkPlugins: [[remarkAstroD2, config]],
+          },
+        })
+      },
+    },
+  }
+}

package/libs/attributes.ts

@@ -0,0 +1,92 @@
+import { z } from 'astro/zod'
+
+export const AttributesSchema = z
+  .object({
+    /**
+     * When specified, the diagram will package multiple boards as 1 SVG which transitions through each board at the
+     * specified interval (in milliseconds).
+     */
+    animateInterval: z.string().optional(),
+    /**
+     * The dark theme to use for the diagrams when the user's system preference is set to dark mode.
+     *
+     * To disable the dark theme and have all diagrams look the same, set this attribute to `'false'`.
+     *
+     * @see https://d2lang.com/tour/themes
+     */
+    darkTheme: z
+      .string()
+      .optional()
+      .transform((value) => (value === 'false' ? false : value)),
+    /**
+     * The padding (in pixels) around the rendered diagram.
+     *
+     * @default 100
+     */
+    pad: z.coerce.number().default(100),
+    /**
+     * Whether to render the diagram as if it was sketched by hand.
+     *
+     * @default 'false'
+     */
+    sketch: z.union([z.literal('true'), z.literal('false')]).default('false'),
+    /**
+     * Defines the target board to render when using composition.
+     * Use `root` to target the root board.
+     *
+     * @see https://d2lang.com/tour/composition
+     */
+    target: z
+      .string()
+      .optional()
+      .transform((value) => (value === 'root' ? '' : value)),
+    /**
+     * The title of the diagram that will be used as the `alt` attribute of the generated image.
+     *
+     * @default 'Diagram'
+     */
+    title: z.string().default('Diagram'),
+    /**
+     * The default theme to use for the diagrams.
+     *
+     * @see https://d2lang.com/tour/themes
+     */
+    theme: z.string().optional(),
+    /**
+     * The width (in pixels) of the diagram.
+     */
+    width: z.coerce.number().optional(),
+  })
+  .default({})
+
+const attributeRegex =
+  /(?<key>[^\s"'=]+)=(?:(?<noQuoteValue>\w+)|'(?<singleQuoteValue>[^']+)'|"(?<doubleQuoteValue>[^"]+))|(?<truthyKey>\w+)/g
+
+export function getAttributes(attributesStr: string | null | undefined) {
+  return AttributesSchema.parse(parseAttributes(attributesStr))
+}
+
+function parseAttributes(attributesStr: string | null | undefined) {
+  if (!attributesStr) {
+    return {}
+  }
+
+  const matches = attributesStr.matchAll(attributeRegex)
+
+  const attributes: Record<string, string> = {}
+
+  for (const match of matches) {
+    const { key, noQuoteValue, singleQuoteValue, doubleQuoteValue, truthyKey } = match.groups ?? {}
+
+    const attributeKey = truthyKey ?? key
+    const attributeValue = truthyKey ? 'true' : noQuoteValue ?? singleQuoteValue ?? doubleQuoteValue
+
+    if (attributeKey && attributeValue) {
+      attributes[attributeKey] = attributeValue
+    }
+  }
+
+  return attributes
+}
+
+export type DiagramAttributes = z.infer<typeof AttributesSchema>

package/libs/d2.ts

@@ -0,0 +1,103 @@
+import fs from 'node:fs/promises'
+
+import type { AstroD2Config } from '../config'
+
+import type { DiagramAttributes } from './attributes'
+import { exec } from './exec'
+
+const viewBoxRegex = /viewBox="\d+ \d+ (?<width>\d+) (?<height>\d+)"/
+
+export async function isD2Installed() {
+  try {
+    await getD2Version()
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function generateD2Diagram(
+  config: AstroD2Config,
+  attributes: DiagramAttributes,
+  input: string,
+  outputPath: string,
+) {
+  const extraArgs = []
+
+  if (
+    (config.theme.dark !== false && attributes.darkTheme !== false) ||
+    (attributes.darkTheme !== undefined && attributes.darkTheme !== false)
+  ) {
+    extraArgs.push(`--dark-theme=${attributes.darkTheme ?? config.theme.dark}`)
+  }
+
+  if (attributes.animateInterval) {
+    extraArgs.push(`--animate-interval=${attributes.animateInterval}`)
+  }
+
+  if (attributes.target !== undefined) {
+    extraArgs.push(`--target='${attributes.target}'`)
+  }
+
+  try {
+    // The `-` argument is used to read from stdin instead of a file.
+    await exec(
+      'd2',
+      [
+        `--layout=${config.layout}`,
+        `--theme=${attributes.theme ?? config.theme.default}`,
+        `--sketch=${attributes.sketch}`,
+        `--pad=${attributes.pad}`,
+        ...extraArgs,
+        '-',
+        outputPath,
+      ],
+      input,
+    )
+  } catch (error) {
+    throw new Error('Failed to generate D2 diagram.', { cause: error })
+  }
+
+  return await getD2DiagramSize(outputPath)
+}
+
+export async function getD2DiagramSize(diagramPath: string): Promise<D2Size> {
+  try {
+    const content = await fs.readFile(diagramPath, 'utf8')
+    const match = content.match(viewBoxRegex)
+    const { height, width } = match?.groups ?? {}
+
+    if (!height || !width) {
+      return
+    }
+
+    const computedHeight = Number.parseInt(height, 10)
+    const computedWidth = Number.parseInt(width, 10)
+
+    return { height: computedHeight, width: computedWidth }
+  } catch (error) {
+    throw new Error(`Failed to get D2 diagram size at '${diagramPath}'.`, { cause: error })
+  }
+}
+
+async function getD2Version() {
+  try {
+    const [version] = await exec('d2', ['--version'])
+
+    if (!version || !/^\d+\.\d+\.\d+$/.test(version)) {
+      throw new Error(`Invalid D2 version, got '${version}'.`)
+    }
+
+    return version
+  } catch (error) {
+    throw new Error('Failed to get D2 version.', { cause: error })
+  }
+}
+
+export type D2Size =
+  | {
+      height: number
+      width: number
+    }
+  | undefined

package/libs/exec.ts

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process'
+
+export function exec(command: string, args: string[], stdin?: string) {
+  return new Promise<string[]>((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: [],
+    })
+
+    const output: string[] = []
+    const errorMessage = `Unable to run command: '${command} ${args.join(' ')}'.`
+
+    child.stdout.on('data', (data: Buffer) => {
+      const lines = data
+        .toString()
+        .split('\n')
+        .filter((line) => line.length > 0)
+
+      output.push(...lines)
+    })
+
+    child.on('error', (error) => {
+      reject(new Error(errorMessage, { cause: error }))
+    })
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(errorMessage))
+
+        return
+      }
+
+      resolve(output)
+    })
+
+    if (stdin) {
+      child.stdin.write(stdin)
+      child.stdin.end()
+    }
+  })
+}

package/libs/integration.ts

@@ -0,0 +1,8 @@
+import { AstroError } from 'astro/errors'
+
+export function throwErrorWithHint(message: string): never {
+  throw new AstroError(
+    message,
+    `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/HiDeoo/astro-d2/issues/new/choose`,
+  )
+}

package/libs/remark.ts

@@ -0,0 +1,102 @@
+import path from 'node:path'
+
+import type { Code, Html, Parent, Root } from 'mdast'
+import { SKIP, visit } from 'unist-util-visit'
+import type { VFile } from 'vfile'
+
+import type { AstroD2Config } from '../config'
+
+import { type DiagramAttributes, getAttributes } from './attributes'
+import { generateD2Diagram, type D2Size, getD2DiagramSize } from './d2'
+import { throwErrorWithHint } from './integration'
+
+export function remarkAstroD2(config: AstroD2Config) {
+  return async function transformer(tree: Root, file: VFile) {
+    const d2Nodes: [node: Code, context: VisitorContext][] = []
+
+    visit(tree, 'code', (node, index, parent) => {
+      if (node.lang === 'd2') {
+        d2Nodes.push([node, { index, parent }])
+      }
+
+      return SKIP
+    })
+
+    if (d2Nodes.length === 0) {
+      return
+    }
+
+    await Promise.all(
+      d2Nodes.map(async ([node, { index, parent }], d2Index) => {
+        const outputPath = getOutputPaths(config, file, d2Index)
+        const attributes = getAttributes(node.meta)
+        let size: D2Size = undefined
+
+        if (config.skipGeneration) {
+          size = await getD2DiagramSize(outputPath.fsPath)
+        } else {
+          try {
+            size = await generateD2Diagram(config, attributes, node.value, outputPath.fsPath)
+          } catch {
+            throwErrorWithHint(
+              `Failed to generate the D2 diagram at ${node.position?.start.line ?? 0}:${node.position?.start.column ?? 0}.`,
+            )
+          }
+        }
+
+        if (parent && index !== undefined) {
+          parent.children.splice(index, 1, makHtmlImgNode(attributes, outputPath.imgPath, size))
+        }
+      }),
+    )
+  }
+}
+
+function makHtmlImgNode(attributes: DiagramAttributes, imgPath: string, size: D2Size): Html {
+  const htmlAttributes: Record<string, string> = {
+    alt: attributes.title,
+    decoding: 'async',
+    loading: 'lazy',
+    src: imgPath,
+  }
+
+  computeImgSize(htmlAttributes, attributes, size)
+
+  return {
+    type: 'html',
+    value: `<img ${Object.entries(htmlAttributes)
+      .map(([key, value]) => `${key}="${value}"`)
+      .join(' ')} />`,
+  }
+}
+
+function getOutputPaths(config: AstroD2Config, file: VFile, nodeIndex: number) {
+  const relativePath = path.relative(file.cwd, file.path).replace(/^src\/(content|pages)\//, '')
+  const parsedRelativePath = path.parse(relativePath)
+
+  const relativeOutputPath = path.join(parsedRelativePath.dir, `${parsedRelativePath.name}-${nodeIndex}.svg`)
+
+  return {
+    fsPath: path.join(file.cwd, 'public', config.output, relativeOutputPath),
+    imgPath: path.posix.join('/', config.output, relativeOutputPath),
+  }
+}
+
+function computeImgSize(htmlAttributes: Record<string, string>, attributes: DiagramAttributes, size: D2Size) {
+  if (attributes.width !== undefined) {
+    htmlAttributes['width'] = String(attributes.width)
+
+    if (size) {
+      const aspectRatio = size.height / size.width
+      htmlAttributes['height'] = String(Math.round(attributes.width * aspectRatio))
+    }
+  } else if (size) {
+    htmlAttributes['width'] = String(size.width)
+    htmlAttributes['height'] = String(size.height)
+  }
+}
+
+interface VisitorContext {
+  index: number | undefined
+  parent: Parent | undefined
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "astro-d2",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Astro integration and remark plugin to transform D2 Markdown code blocks into diagrams.",
+  "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "unist-util-visit": "5.0.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "4.0.3",
+    "remark": "15.0.1",
+    "vfile": "6.0.1",
+    "vitest": "1.2.2"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@8.15.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "markdown",
+    "d2",
+    "diagram",
+    "astro-integration"
+  ],
+  "homepage": "https://github.com/HiDeoo/astro-d2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HiDeoo/astro-d2.git"
+  },
+  "bugs": "https://github.com/HiDeoo/astro-d2/issues",
+  "scripts": {
+    "test": "vitest",
+    "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
+  }
+}