@blaaiz/docs-core 0.1.0

package/styles/home.css

@@ -0,0 +1,376 @@
+/*
+ * @blaaiz/docs-core — the landing-page layout.
+ *
+ * Import after docs.css, on a site that has a home page:
+ *   @import '@blaaiz/docs-core/styles/home.css';
+ *
+ * A landing page is one MDX file of plain elements carrying these classes — no
+ * component to import, nothing to configure:
+ *
+ *   <div className="home-page">
+ *     <div className="home-hero">
+ *       <div className="home-hero__content">
+ *         <span className="home-hero__eyebrow"><b>@example/docs</b> · v1</span>
+ *         <h1 className="home-hero__title">Everything the API can do.</h1>
+ *         <p className="home-hero__body">One sentence about the product.</p>
+ *         <div className="home-hero__actions">
+ *           <a className="home-hero__cta" href="/docs/quickstart">Start here</a>
+ *           <a className="home-hero__ghost" href="/docs/reference">Reference</a>
+ *         </div>
+ *       </div>
+ *     </div>
+ *     <div className="home-section"> … </div>
+ *   </div>
+ *
+ * Blocks: `home-hero`, `home-section` (with `__label`, `__title`, `__body`),
+ * `home-grid` of `home-card`s, `home-split` with a `home-panel` code frame, and
+ * `home-owners` of `home-owner` columns.
+ *
+ * Every colour is a `--color-fd-*` theme token, so the page follows the site's
+ * palette and both themes. Nothing here hardcodes a brand. Type follows
+ * `--font-code` where a monospace face is wanted, and falls back to the system
+ * monospace stack on a site that declares none.
+ *
+ * Keep each text-bearing element's tag, text, and closing tag on ONE line in
+ * MDX. A child that starts on its own line is parsed as Markdown and wrapped in
+ * a `<p>`, which nests a `<p>` inside a `<p>` and breaks hydration.
+ */
+
+.home-page {
+  --home-gutter: clamp(1.25rem, 4vw, 3.5rem);
+  --home-mono: var(--font-code, var(--font-mono, ui-monospace, 'SF Mono', Menlo, monospace));
+  width: 100%;
+  padding-bottom: 5rem;
+}
+
+/* --- Hero ---------------------------------------------------------------- */
+
+.home-hero {
+  position: relative;
+  padding: clamp(3rem, 8vw, 6.5rem) var(--home-gutter) clamp(2.5rem, 5vw, 4rem);
+  overflow: hidden;
+  border-bottom: 1px solid var(--color-fd-border);
+}
+
+/* A soft wash of the site's accent behind the headline. */
+.home-hero::before {
+  content: '';
+  position: absolute;
+  top: -40%;
+  left: 50%;
+  width: min(900px, 120%);
+  aspect-ratio: 1;
+  transform: translateX(-50%);
+  background: radial-gradient(
+    circle,
+    color-mix(in oklab, var(--color-fd-primary) 16%, transparent) 0%,
+    transparent 62%
+  );
+  pointer-events: none;
+}
+
+.home-hero__content {
+  position: relative;
+  max-width: 44rem;
+}
+
+.home-hero__eyebrow {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.3rem 0.7rem 0.3rem 0.55rem;
+  margin-bottom: 1.4rem;
+  border: 1px solid var(--color-fd-border);
+  border-radius: 999px;
+  background: var(--color-fd-card);
+  font-family: var(--home-mono);
+  font-size: 12px;
+  letter-spacing: 0.01em;
+  color: var(--color-fd-muted-foreground);
+}
+
+.home-hero__eyebrow b {
+  color: var(--color-fd-primary);
+  font-weight: 600;
+}
+
+.home-hero__title {
+  margin: 0;
+  font-size: clamp(2.1rem, 5.2vw, 3.5rem);
+  font-weight: 640;
+  line-height: 1.06;
+  letter-spacing: -0.035em;
+}
+
+/* `<em>` in the headline is an accent, not an italic. */
+.home-hero__title em {
+  font-style: normal;
+  color: var(--color-fd-primary);
+}
+
+.home-hero__body {
+  margin: 1.35rem 0 0;
+  max-width: 38rem;
+  font-size: clamp(1rem, 1.4vw, 1.125rem);
+  line-height: 1.68;
+  color: var(--color-fd-muted-foreground);
+}
+
+.home-hero__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  margin-top: 2.1rem;
+}
+
+.home-hero__cta,
+.home-hero__ghost {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.7rem 1.25rem;
+  border-radius: 10px;
+  font-size: 14.5px;
+  font-weight: 550;
+  text-decoration: none;
+  transition:
+    background 0.15s ease,
+    border-color 0.15s ease,
+    transform 0.15s ease;
+}
+
+.home-hero__cta {
+  background: var(--color-fd-primary);
+  color: var(--color-fd-primary-foreground, #fff);
+  border: 1px solid var(--color-fd-primary);
+}
+
+.home-hero__cta:hover {
+  transform: translateY(-1px);
+  background: color-mix(in oklab, var(--color-fd-primary) 88%, black);
+}
+
+.home-hero__ghost {
+  border: 1px solid var(--color-fd-border);
+  background: var(--color-fd-card);
+  color: var(--color-fd-foreground);
+}
+
+.home-hero__ghost:hover {
+  border-color: var(--color-fd-primary);
+  background: color-mix(in oklab, var(--color-fd-primary) 7%, transparent);
+}
+
+/* --- Section shell, reused by every band below the hero ------------------ */
+
+.home-section {
+  padding: clamp(2.5rem, 5vw, 4rem) var(--home-gutter) 0;
+}
+
+.home-section__label {
+  margin: 0 0 0.4rem;
+  font-family: var(--home-mono);
+  font-size: 11.5px;
+  font-weight: 600;
+  letter-spacing: 0.09em;
+  text-transform: uppercase;
+  color: var(--color-fd-primary);
+}
+
+.home-section__title {
+  margin: 0 0 0.6rem;
+  font-size: clamp(1.4rem, 2.4vw, 1.85rem);
+  font-weight: 620;
+  letter-spacing: -0.025em;
+}
+
+.home-section__body {
+  margin: 0 0 1.8rem;
+  max-width: 40rem;
+  font-size: 15.5px;
+  line-height: 1.7;
+  color: var(--color-fd-muted-foreground);
+}
+
+/* --- Card grid ----------------------------------------------------------- */
+
+.home-grid {
+  display: grid;
+  gap: 0.9rem;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 17rem), 1fr));
+}
+
+.home-card {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  padding: 1.15rem 1.3rem 1.25rem;
+  border: 1px solid var(--color-fd-border);
+  border-radius: 14px;
+  background: var(--color-fd-card);
+  text-decoration: none;
+  color: inherit;
+  transition:
+    border-color 0.15s ease,
+    background 0.15s ease,
+    transform 0.15s ease;
+}
+
+a.home-card:hover {
+  transform: translateY(-2px);
+  border-color: var(--color-fd-primary);
+  background: color-mix(in oklab, var(--color-fd-primary) 5%, var(--color-fd-card));
+}
+
+.home-card__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  margin-bottom: 0.35rem;
+  border-radius: 9px;
+  background: color-mix(in oklab, var(--color-fd-primary) 12%, transparent);
+  color: var(--color-fd-primary);
+  font-family: var(--home-mono);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.home-card__title {
+  font-size: 15.5px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+
+.home-card__body {
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--color-fd-muted-foreground);
+}
+
+/* --- Two-column split: prose beside a code panel ------------------------- */
+
+.home-split {
+  display: grid;
+  gap: clamp(1.25rem, 3vw, 2.5rem);
+  align-items: start;
+  grid-template-columns: 1fr;
+}
+
+@media (min-width: 960px) {
+  .home-split {
+    grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.1fr);
+  }
+}
+
+.home-panel {
+  border: 1px solid var(--color-fd-border);
+  border-radius: 14px;
+  background: color-mix(in oklab, var(--color-fd-card) 92%, black);
+  overflow: hidden;
+}
+
+/* On a dark page the card is already near-black, so lift the panel instead. */
+.dark .home-panel {
+  background: color-mix(in oklab, var(--color-fd-card) 92%, white);
+}
+
+.home-panel__bar {
+  display: flex;
+  align-items: center;
+  gap: 0.55rem;
+  padding: 0.7rem 1rem;
+  border-bottom: 1px solid var(--color-fd-border);
+  font-family: var(--home-mono);
+  font-size: 12px;
+  color: var(--color-fd-muted-foreground);
+}
+
+.home-panel__dots {
+  display: inline-flex;
+  gap: 5px;
+}
+
+.home-panel__dots i {
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  background: var(--color-fd-border);
+}
+
+.home-panel pre {
+  margin: 0;
+  padding: 1rem 1.15rem 1.2rem;
+  overflow-x: auto;
+  font-family: var(--home-mono);
+  font-size: 12.8px;
+  line-height: 1.85;
+  color: var(--color-fd-foreground);
+}
+
+/* Two hand-rolled highlight classes for the sample: `c` a comment, `k` a key. */
+.home-panel .c {
+  color: var(--color-fd-muted-foreground);
+}
+
+.home-panel .k {
+  color: var(--color-fd-primary);
+}
+
+/* --- Ownership columns --------------------------------------------------- */
+
+.home-owners {
+  display: grid;
+  gap: 0.9rem;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 20rem), 1fr));
+}
+
+.home-owner {
+  padding: 1.2rem 1.35rem 1.35rem;
+  border: 1px solid var(--color-fd-border);
+  border-radius: 14px;
+  background: var(--color-fd-card);
+}
+
+.home-owner h3 {
+  margin: 0 0 0.15rem;
+  font-family: var(--home-mono);
+  font-size: 13px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  color: var(--color-fd-primary);
+}
+
+.home-owner p {
+  margin: 0 0 0.9rem;
+  font-size: 13.5px;
+  color: var(--color-fd-muted-foreground);
+}
+
+.home-owner ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+}
+
+.home-owner li {
+  padding-left: 1.1rem;
+  position: relative;
+  font-size: 14px;
+  line-height: 1.55;
+}
+
+.home-owner li::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 0.55em;
+  width: 6px;
+  height: 6px;
+  border-radius: 2px;
+  background: color-mix(in oklab, var(--color-fd-primary) 55%, transparent);
+}

package/templates/init/content/docs/index.mdx.tmpl

@@ -0,0 +1,52 @@
+---
+title: __NAME__
+description: Everything you need to get started.
+---
+
+Welcome. This page is the front door of your documentation site.
+
+`content/docs.json` is the single source of truth for the navigation. Add a page
+to it, create the matching `.mdx` file under `content/docs/`, and it appears in
+the sidebar in exactly the order you declared.
+
+## Write a page
+
+Every page is Markdown with a frontmatter block.
+
+```mdx title="content/docs/guides/install.mdx"
+---
+title: Install
+description: Add the client library to your project.
+---
+
+Run `npm install our-sdk`, then set `OUR_API_KEY` in your environment.
+```
+
+Then declare it in `content/docs.json`:
+
+```json
+{ "tab": "Documentation", "icon": "book", "pages": ["index", "guides/install"] }
+```
+
+## Components you can use
+
+The framework ships Mintlify-compatible components. Use them anywhere in a page.
+
+<Info>
+  `Info`, `Tip`, `Warning`, `Note`, and `Check` render a callout.
+</Info>
+
+<Steps>
+  <Step title="Edit the navigation">Add the page to `content/docs.json`.</Step>
+  <Step title="Write the page">Create the `.mdx` file under `content/docs/`.</Step>
+  <Step title="Reload">The development server picks the change up.</Step>
+</Steps>
+
+## Next
+
+- Set the brand colours and the logo in `docs.config.ts`.
+- Gate the site to your workspace with `auth: { mode: 'workspace', ... }`.
+- Publish an OpenAPI reference with a try-it playground.
+- Turn on Ask AI with one line of config.
+
+Full documentation: <https://docs-core.blaaiz.dev>

package/templates/init/content/docs/meta.json.tmpl

@@ -0,0 +1,3 @@
+{
+  "pages": ["index"]
+}

package/templates/init/content/docs.json.tmpl

@@ -0,0 +1,12 @@
+{
+  "name": "__NAME__",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "icon": "book",
+        "pages": ["index"]
+      }
+    ]
+  }
+}

package/templates/init/content/nav.json.tmpl

@@ -0,0 +1,7 @@
+[
+  {
+    "text": "Documentation",
+    "url": "/docs",
+    "icon": "book"
+  }
+]

package/templates/init/docs.config.ts.tmpl

@@ -0,0 +1,36 @@
+import { defineDocsConfig } from '@blaaiz/docs-core';
+
+/**
+ * Site configuration.
+ *
+ * The framework owns the behaviour. This file owns the values that change per
+ * site: the brand, the access mode, the origins the try-it proxy may reach, and
+ * the features the site opts into. No secret ever lives here — config names an
+ * environment variable, and the server reads the value at runtime.
+ */
+export default defineDocsConfig({
+  theme: {
+    name: '__NAME__',
+    colors: { primary: '#4c63f5' },
+    darkColors: { primary: '#8b9bff' },
+  },
+
+  // 'public' needs no middleware, no sign-in page, and no auth routes. Switch to
+  // { mode: 'workspace', allowedDomains: [...], providers: { ... } } to gate the
+  // site to your own people.
+  auth: 'public',
+
+  // Security-critical: the exhaustive list of upstream API origins the try-it
+  // playground may forward a request to. Anything else is refused. Leave it
+  // empty until the site publishes an API reference.
+  proxy: { allowedOrigins: [] },
+
+  features: {
+    // Show the "Copy page / View as Markdown" control on every page.
+    copyPage: true,
+  },
+
+  // Ask AI: uncomment the line below, set ANTHROPIC_API_KEY on the server, and
+  // mount the route and the panel. Naming a provider is the whole setup.
+  // ai: { provider: 'anthropic' },
+});

package/templates/init/env.example.tmpl

@@ -0,0 +1,15 @@
+# Server-side environment for the docs site. Copy this file to .env.local, fill in
+# only what the site uses, and keep .env.local out of version control. Every value
+# is read on the server; none of them reaches the browser.
+
+# Signs the session cookie on a workspace-gated site. Generate with: openssl rand -hex 32
+# DOCS_SESSION_SECRET=
+
+# The one shared secret readers type in, for the workspace `secret` sign-in provider.
+# DOCS_ACCESS_SECRET=
+
+# API key for Ask AI with ai: { provider: 'anthropic' }.
+# ANTHROPIC_API_KEY=
+
+# API key for Ask AI with ai: { provider: 'openai' }.
+# OPENAI_API_KEY=