@casoon/pages-theme 0.0.0-stage → 0.12.8

package/fonts/OFL.txt

@@ -0,0 +1,95 @@
+Inter: Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+Onest: Copyright 2021 The Onest Project Authors (https://github.com/simpals/onest)
+JetBrains Mono: Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/index.ts

@@ -0,0 +1,204 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import mdx from '@astrojs/mdx';
+import type { AstroIntegration } from 'astro';
+import type { Lang } from './lib/i18n';
+import { renderOgImage } from './lib/og';
+import { projectVersion } from './lib/version';
+
+export interface PackageLink {
+  /** Label shown in the footer and as badge, e.g. "crates.io" or "npm". */
+  label: string;
+  href: string;
+}
+
+export interface CasoonPagesOptions {
+  /** Project name as shown in the header, e.g. "runemark". */
+  name: string;
+  /** One sentence; used as default meta description. */
+  description: string;
+  /** A few words for the start page's `<title>` and the OG image: "<name> – <tagline> | CASOON". */
+  tagline?: string;
+  /** The project's own landing page, e.g. "https://example.com". Linked in header and footer. */
+  website?: string;
+  /** Slug of the project's entry on casoon.dev (`#projekt-<slug>`), or false. Default: repository name. */
+  catalog?: string | false;
+  /** GitHub repository as "owner/name". Omit for a private repository: no GitHub or edit links. */
+  repo?: string;
+  /** Current release, shown in the header and on docs pages.
+   *  Omitted: read from package.json or Cargo.toml next to site/. `false` shows none. */
+  version?: string | false;
+  /** SPDX licence identifier, or false for proprietary code (no licence named). Default: "MIT". */
+  license?: string | false;
+  /** Default branch, used for "Edit this page" links. Default: "main". */
+  branch?: string;
+  /** Project accent colour for light and dark theme. Default: CASOON petrol. Both must meet 4.5:1 on the page background. */
+  accent?: { light: string; dark: string };
+  /** Registry and API-doc links (crates.io, npm, docs.rs …). */
+  packages?: PackageLink[];
+  /** Docs sidebar groups: folder name in docs/ → label, in display order. Root-level pages join the first group. */
+  docsGroups?: Record<string, string>;
+  /** Path to the docs folder relative to the repository root, for edit links. Default: "docs". */
+  docsDir?: string;
+  /** Path to CHANGELOG.md relative to the site root, or false. Default: "../CHANGELOG.md". */
+  changelog?: string | false;
+  /** Module exporting `examples: ShowcaseExample[]`, relative to the site root, or false. Default: "./src/showcase.ts". */
+  showcase?: string | false;
+  /**
+   * Live demo: the header label linking to /demo/, or false for none. Default: false.
+   *
+   * The page itself belongs to the project (`src/pages/demo.astro`) and wraps its
+   * running instance in the `Demo` component — the theme only adds the entry.
+   */
+  demo?: string | false;
+  /**
+   * Module exporting `components: Record<string, AstroComponent>`, relative to the site
+   * root, for docs MDX next to the theme's own. `docs/` cannot import anything, so this
+   * is how a page reaches something only the site can build — a component rendering the
+   * project's own output, say. Same name as a theme component: the project's wins.
+   */
+  mdxComponents?: string;
+  /** Language of the theme's own UI strings and of `<html lang>`. Default: "en". */
+  lang?: Lang;
+  /** Lead paragraph of the showcase overview, instead of the theme's generic one. */
+  showcaseLead?: string;
+}
+
+export interface ResolvedConfig
+  extends Required<
+    Omit<
+      CasoonPagesOptions,
+      'accent' | 'changelog' | 'showcase' | 'demo' | 'mdxComponents' | 'catalog'
+    >
+  > {
+  accent: { light: string; dark: string } | null;
+  /** Absolute path to CHANGELOG.md, or null when disabled. */
+  changelog: string | null;
+  hasShowcase: boolean;
+  /** Header label of the demo page, or an empty string when there is none. */
+  demo: string;
+  /** casoon.dev catalog slug, or an empty string when there is none. */
+  catalog: string;
+}
+
+const CONFIG_ID = 'virtual:casoon-pages/config';
+const SHOWCASE_ID = 'virtual:casoon-pages/showcase';
+const MDX_COMPONENTS_ID = 'virtual:casoon-pages/mdx-components';
+
+export default function casoonPages(options: CasoonPagesOptions): AstroIntegration {
+  let resolved: ResolvedConfig;
+  /** Absolute URL of the site's base path, or null without `site`. */
+  let site: URL | null = null;
+  return {
+    name: '@casoon/pages-theme',
+    hooks: {
+      'astro:config:setup': ({ config, updateConfig, injectRoute }) => {
+        site = config.site ? new URL(config.base.replace(/\/?$/, '/'), config.site) : null;
+        const root = fileURLToPath(config.root);
+        const showcasePath =
+          options.showcase === false
+            ? null
+            : resolve(root, options.showcase ?? './src/showcase.ts');
+
+        resolved = {
+          name: options.name,
+          description: options.description,
+          tagline: options.tagline ?? '',
+          website: options.website ?? '',
+          catalog:
+            options.catalog === false ? '' : (options.catalog ?? options.repo?.split('/')[1] ?? ''),
+          repo: options.repo ?? '',
+          version:
+            options.version === false
+              ? ''
+              : (options.version ?? projectVersion(resolve(root, '..'))),
+          license: options.license ?? 'MIT',
+          branch: options.branch ?? 'main',
+          accent: options.accent ?? null,
+          packages: options.packages ?? [],
+          docsGroups: options.docsGroups ?? {},
+          docsDir: options.docsDir ?? 'docs',
+          changelog:
+            options.changelog === false
+              ? null
+              : resolve(root, options.changelog ?? '../CHANGELOG.md'),
+          hasShowcase: showcasePath !== null,
+          demo: options.demo === false || options.demo === undefined ? '' : options.demo,
+          lang: options.lang ?? 'en',
+          showcaseLead: options.showcaseLead ?? '',
+        };
+
+        const route = (pattern: string, file: string) =>
+          injectRoute({ pattern, entrypoint: `@casoon/pages-theme/routes/${file}` });
+        route('/docs/[...slug]', 'docs/[...slug].astro');
+        if (resolved.hasShowcase) {
+          route('/showcase', 'showcase/index.astro');
+          route('/showcase/[slug]', 'showcase/[slug].astro');
+        }
+        if (resolved.changelog) route('/changelog', 'changelog.astro');
+        route('/404', '404.astro');
+
+        const modules: Record<string, string> = {
+          [CONFIG_ID]: `export default ${JSON.stringify(resolved)};`,
+          [SHOWCASE_ID]: showcasePath
+            ? `export { examples } from ${JSON.stringify(showcasePath)};`
+            : 'export const examples = [];',
+          [MDX_COMPONENTS_ID]: options.mdxComponents
+            ? `export { components } from ${JSON.stringify(resolve(root, options.mdxComponents))};`
+            : 'export const components = {};',
+        };
+
+        updateConfig({
+          integrations: [mdx()],
+          markdown: { shikiConfig: { theme: 'css-variables' } },
+          vite: {
+            plugins: [
+              {
+                name: 'casoon-pages-virtual',
+                resolveId: (id: string) => (id in modules ? `\0${id}` : undefined),
+                load: (id: string) =>
+                  id.startsWith('\0') && id.slice(1) in modules ? modules[id.slice(1)] : undefined,
+              },
+            ],
+            // docs/, examples/ and CHANGELOG.md live next to site/ in the project repository.
+            server: { fs: { allow: [resolve(root, '..')] } },
+          },
+        });
+      },
+      // Project pages may import the virtual modules too (`config.version` on a start page),
+      // so the declarations go into the project's generated types, not just the theme's.
+      'astro:config:done': ({ injectTypes }) => {
+        injectTypes({
+          filename: 'virtual.d.ts',
+          content: readFileSync(new URL('./virtual.d.ts', import.meta.url), 'utf8').replace(
+            "'./index'",
+            "'@casoon/pages-theme'"
+          ),
+        });
+      },
+      // Sitemap and OG image need absolute URLs, so both depend on `site`.
+      'astro:build:done': async ({ dir, pages }) => {
+        const base = site;
+        if (!base) return;
+        // A project that writes its own sitemap keeps it: this one is the fallback, not the
+        // authority. It only sees that file when the project's integration is listed first.
+        const sitemap = new URL('sitemap.xml', dir);
+        if (!existsSync(sitemap)) {
+          const urls = pages
+            .map((page) => page.pathname)
+            .filter((pathname) => pathname !== '404/')
+            .map((pathname) => `  <url><loc>${new URL(pathname, base).href}</loc></url>`);
+          await writeFile(
+            sitemap,
+            '<?xml version="1.0" encoding="UTF-8"?>\n' +
+              '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+              `${urls.join('\n')}\n</urlset>\n`
+          );
+        }
+        await writeFile(new URL('og.png', dir), await renderOgImage(resolved, base));
+      },
+    },
+  };
+}

package/layouts/Base.astro

@@ -0,0 +1,131 @@
+---
+import '../styles/fonts.css';
+import '../styles/tokens.css';
+import '../styles/base.css';
+import config from 'virtual:casoon-pages/config';
+import favicon from '../assets/favicon.svg';
+import Footer from '../components/Footer.astro';
+import Header from '../components/Header.astro';
+import { t } from '../lib/i18n';
+import { CASOON_URL, url } from '../lib/url';
+
+interface Props {
+  /** Page title; the project name is appended. Omit on the home page. */
+  title?: string;
+  description?: string;
+}
+
+const { title, description = config.description } = Astro.props;
+const s = t(config.lang);
+const fullTitle = title
+  ? `${title} · ${config.name}`
+  : `${config.name}${config.tagline && ` – ${config.tagline}`} | CASOON`;
+const canonical = Astro.site ? new URL(Astro.url.pathname, Astro.site).href : undefined;
+// Written by the integration after the build (index.ts), so only with `site`.
+const home = Astro.site && new URL(url(), Astro.site).href;
+const ogImage = Astro.site && new URL(url('og.png'), Astro.site).href;
+const sameAs = [config.website, ...config.packages.map((p) => p.href)].filter(Boolean);
+
+// tokens.css sets --accent with the same selectors and is linked after this inline style, so the
+// selectors repeat :root to outrank it whatever the order in <head> (scripts/test-accent.mjs).
+const accentCss = config.accent
+  ? `:root:root{--accent:${config.accent.light}}` +
+    `:root:root[data-theme="dark"]{--accent:${config.accent.dark}}` +
+    `@media (prefers-color-scheme:dark){:root:root:not([data-theme="light"]){--accent:${config.accent.dark}}}`
+  : '';
+
+const structuredData = {
+  '@context': 'https://schema.org',
+  '@type': 'SoftwareSourceCode',
+  name: config.name,
+  description: config.description,
+  ...(home && { url: home }),
+  ...(sameAs.length > 0 && { sameAs }),
+  ...(config.repo && { codeRepository: `https://github.com/${config.repo}` }),
+  ...(config.license && { license: `https://spdx.org/licenses/${config.license}.html` }),
+  ...(config.version && { version: config.version }),
+  author: { '@type': 'Person', name: 'Jörn Seidel', url: CASOON_URL },
+  publisher: { '@type': 'Organization', name: 'CASOON', url: CASOON_URL },
+};
+---
+
+<!doctype html>
+<html lang={config.lang}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{fullTitle}</title>
+    <meta name="description" content={description} />
+    {canonical && <link rel="canonical" href={canonical} />}
+    <meta property="og:type" content="website" />
+    <meta property="og:title" content={fullTitle} />
+    <meta property="og:description" content={description} />
+    {canonical && <meta property="og:url" content={canonical} />}
+    {
+      ogImage && (
+        <>
+          <meta property="og:image" content={ogImage} />
+          <meta property="og:image:width" content="1200" />
+          <meta property="og:image:height" content="630" />
+          <meta property="og:image:alt" content={`${config.name} – ${config.tagline || config.description}`} />
+          <meta name="twitter:card" content="summary_large_image" />
+          <link rel="sitemap" href={url('sitemap.xml')} />
+        </>
+      )
+    }
+    <link rel="icon" href={favicon.src} type="image/svg+xml" />
+    {accentCss && <style is:inline set:html={accentCss} />}
+    <script is:inline>
+      // Theme before first paint: stored choice, else system preference.
+      (() => {
+        let theme = null;
+        try {
+          theme = localStorage.getItem('casoon-pages-theme');
+        } catch {}
+        if (theme !== 'dark' && theme !== 'light') {
+          theme = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+        }
+        document.documentElement.dataset.theme = theme;
+      })();
+    </script>
+    <script is:inline type="application/ld+json" set:html={JSON.stringify(structuredData)} />
+  </head>
+  <body>
+    <a class="skip-link" href="#main">{s.skipLink}</a>
+    <Header />
+    <main id="main">
+      <slot />
+    </main>
+    <Footer />
+    <script is:inline>
+      (() => {
+        const root = document.documentElement;
+        for (const button of document.querySelectorAll('[data-theme-toggle]')) {
+          button.hidden = false;
+          button.setAttribute('aria-pressed', String(root.dataset.theme === 'dark'));
+          button.addEventListener('click', () => {
+            const theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
+            root.dataset.theme = theme;
+            button.setAttribute('aria-pressed', String(theme === 'dark'));
+            try {
+              localStorage.setItem('casoon-pages-theme', theme);
+            } catch {}
+          });
+        }
+        if (!navigator.clipboard) return;
+        for (const button of document.querySelectorAll('[data-copy]')) {
+          button.hidden = false;
+          const label = button.textContent;
+          button.addEventListener('click', async () => {
+            const source = document.getElementById(button.dataset.copy);
+            await navigator.clipboard.writeText(source.textContent.trim());
+            button.textContent = button.dataset.copied;
+            setTimeout(() => {
+              button.textContent = label;
+            }, 1600);
+          });
+        }
+      })();
+    </script>
+  </body>
+</html>