Turn docs-smoke into @inth/docs demo app #3
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| { | ||
| "$schema": "https://ui.shadcn.com/schema.json", | ||
| "style": "radix-nova", | ||
| "rsc": false, | ||
| "tsx": true, | ||
| "tailwind": { | ||
| "config": "", | ||
| "css": "src/styles.css", | ||
| "baseColor": "neutral", | ||
| "cssVariables": true, | ||
| "prefix": "" | ||
| }, | ||
| "iconLibrary": "tabler", | ||
| "rtl": false, | ||
| "aliases": { | ||
| "components": "@/components", | ||
| "utils": "@/lib/utils", | ||
| "ui": "@/components/ui", | ||
| "lib": "@/lib", | ||
| "hooks": "@/hooks" | ||
| }, | ||
| "registries": {} | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| title: "AutoTypeTable Fixture" | ||
| description: "Pipeline-only fixture for type extraction coverage." | ||
| --- | ||
|
|
||
| # AutoTypeTable Fixture | ||
|
|
||
| <AutoTypeTable | ||
| name="PipelineExampleOptions" | ||
| path="./apps/docs-smoke/type-fixtures/pipeline-example.ts" | ||
| /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| --- | ||
| title: "Components Fixture" | ||
| description: "Render the runtime-facing adapters from @inth/docs in one browser route." | ||
| --- | ||
|
|
||
| # Components Fixture | ||
|
|
||
| <Callout variant="success" title="Runtime fixture"> | ||
| This page intentionally exercises the browser-facing adapters without replacing them with shadcn variants. | ||
| </Callout> | ||
|
|
||
| ## Authoring Example | ||
|
|
||
| ```mdx | ||
| <Callout variant="success" title="Runtime fixture"> | ||
| Render the exported adapters through your shared `mdxComponents` map. | ||
| </Callout> | ||
|
|
||
| <PackageCommandTabs command="{pm} add @inth/docs" /> | ||
|
|
||
| <Tabs items={["Overview", "Types"]}> | ||
| <Tab value="Overview">Tabs hydrate in the browser.</Tab> | ||
| <Tab value="Types">Use `TypeTable` when the type data already exists in MDX.</Tab> | ||
| </Tabs> | ||
|
|
||
| <Mermaid chart={`flowchart LR | ||
| A[MDX] --> B[mdxComponents] | ||
| B --> C[Rendered route] | ||
| `} /> | ||
|
|
||
| <TypeTable | ||
| type={{ | ||
| command: { | ||
| type: "string", | ||
| description: "Command template with a {pm} placeholder.", | ||
| required: true, | ||
| }, | ||
| }} | ||
| /> | ||
|
|
||
| <AutoTypeTable | ||
| name="PipelineExampleOptions" | ||
| path="./apps/docs-smoke/type-fixtures/pipeline-example.ts" | ||
| type={pipelineExampleType} | ||
| /> | ||
| ``` | ||
|
|
||
| `AutoTypeTable` still needs extracted `type` data from the route or conversion pipeline. This demo renders that extracted output on `/docs`. | ||
|
|
||
| <Cards> | ||
| <Card title="Quickstart route" description="Internal docs route rendered by the package card component." href="/docs/guides/quickstart" /> | ||
| <Card title="External reference" description="External links should preserve safe target and rel attributes." href="https://example.com/docs" /> | ||
| </Cards> | ||
|
|
||
| <Steps> | ||
| <Step title="Author MDX"> | ||
| Start with semantic components such as `Callout`, `Tabs`, `Cards`, and `TypeTable`. | ||
| </Step> | ||
| <Step title="Render in TanStack Start"> | ||
| Import the `.mdx` file directly and provide `mdxComponents` through the shared runtime map. | ||
| </Step> | ||
| <Step title="Validate separately"> | ||
| Keep `AutoTypeTable` in pipeline coverage where source extraction actually happens. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| <PackageCommandTabs command="{pm} add @inth/docs" /> | ||
|
|
||
| <Tabs items={["Overview", "Tables", "Pipeline note"]}> | ||
| <Tab value="Overview"> | ||
| This tabset proves the package adapters hydrate correctly inside the demo app. | ||
| </Tab> | ||
| <Tab value="Tables"> | ||
| `TypeTable` is safe to render live because all of its data is already present in the MDX payload. | ||
| </Tab> | ||
| <Tab value="Pipeline note"> | ||
| `AutoTypeTable` is not shown live here because extraction depends on a stable build-time file system base path. | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| <Mermaid chart={`flowchart LR | ||
| A[MDX fixture] --> B[mdxComponents] | ||
| B --> C[TanStack Start route] | ||
| C --> D[Playwright coverage] | ||
| `} /> | ||
|
|
||
| <TypeTable | ||
| type={{ | ||
| command: { | ||
| type: "string", | ||
| description: "Command template with a {pm} placeholder.", | ||
| required: true, | ||
| }, | ||
| commands: { | ||
| type: "Record<PackageManager, string>", | ||
| description: "Explicit per-manager overrides when templates are not enough.", | ||
| }, | ||
| defaultManager: { | ||
| type: "\"npm\" | \"pnpm\" | \"yarn\" | \"bun\"", | ||
| description: "The tab that should be active on first render.", | ||
| default: "npm", | ||
| }, | ||
| }} | ||
| /> | ||
|
|
||
| <Callout variant="canary" title="Pipeline-only coverage"> | ||
| `AutoTypeTable` is verified by the markdown conversion fixture at `content/docs/guides/auto-type-table-fixture.mdx` and by the dedicated pipeline test script. | ||
| </Callout> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,16 +1,98 @@ | ||
| --- | ||
| title: "@inth/docs" | ||
| description: "Package docs for runtime adapters, remark plugins, conversion, LLM output, and linting." | ||
| --- | ||
|
|
||
| # @inth/docs | ||
|
|
||
| `@inth/docs` has five package surfaces: | ||
|
|
||
| <TypeTable | ||
| type={{ | ||
| "@inth/docs": { | ||
| type: "runtime", | ||
| description: "React adapters and `mdxComponents` for browser-rendered MDX.", | ||
| required: true, | ||
| }, | ||
| "@inth/docs/remark": { | ||
| type: "pipeline", | ||
| description: "remark plugins and `defaultRemarkPlugins` for MDX processing.", | ||
| required: true, | ||
| }, | ||
| "@inth/docs/convert": { | ||
| type: "pipeline", | ||
| description: "`convertMdxFile`, `convertSingleMdxFile`, and `convertAllMdx`.", | ||
| required: true, | ||
| }, | ||
| "@inth/docs/llm": { | ||
| type: "pipeline", | ||
| description: "Generate `llms.txt` and topic-scoped agent context files.", | ||
| }, | ||
| "@inth/docs/lint": { | ||
| type: "pipeline", | ||
| description: "Validation APIs and the `inth-docs-lint` CLI.", | ||
| }, | ||
| }} | ||
| /> | ||
|
|
||
| ## Install | ||
|
|
||
| <PackageCommandTabs command="{pm} install @inth/docs" /> | ||
|
|
||
| ## Runtime integration | ||
|
|
||
| Use the root package when you want to render authored MDX in a React app. | ||
|
|
||
| ```tsx | ||
| import { mdxComponents } from "@inth/docs"; | ||
|
|
||
| const components = { | ||
| ...mdxComponents, | ||
| }; | ||
| ``` | ||
|
|
||
| The root export is the runtime contract. It is not tied to shadcn, TanStack Start, or any specific docs shell. | ||
|
|
||
| ## Convert MDX | ||
|
|
||
| Use the conversion and remark packages when you want markdown output instead of browser rendering. | ||
|
|
||
| ```ts | ||
| import { convertAllMdx } from "@inth/docs/convert"; | ||
| import { defaultRemarkPlugins, remarkInclude } from "@inth/docs/remark"; | ||
|
|
||
| await convertAllMdx({ | ||
| srcDir: "content", | ||
| outDir: "public", | ||
| remarkPlugins: [remarkInclude, ...defaultRemarkPlugins], | ||
| }); | ||
| ``` | ||
|
|
||
| ## What to open in this app | ||
|
|
||
| <Cards> | ||
| <Card | ||
| title="Quickstart" | ||
| description="Shows the basic conversion flow plus hydrated `Tabs` and `PackageCommandTabs`." | ||
| href="/docs/guides/quickstart" | ||
| /> | ||
| <Card | ||
| title="Components Fixture" | ||
| description="Shows the runtime adapters rendered together through `mdxComponents`." | ||
| href="/docs/guides/components-fixture" | ||
| /> | ||
| </Cards> | ||
|
|
||
| ## Validation layers | ||
|
|
||
| <Steps> | ||
| <Step title="Package tests"> | ||
| Cover semantic HTML and safe runtime behavior in `packages/docs/src/**/*.test.ts*`. | ||
| </Step> | ||
| <Step title="Pipeline fixtures"> | ||
| Cover conversion, extraction, and LLM output in `apps/docs-smoke/scripts` and `apps/docs-smoke/content`. | ||
| </Step> | ||
| <Step title="Browser coverage"> | ||
| Cover hydration and interactive adapters in the Playwright suite for this app. | ||
| </Step> | ||
| </Steps> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,9 @@ | ||
| { | ||
| "title": "Docs", | ||
| "pages": [ | ||
| "index", | ||
| "guides/quickstart", | ||
| "guides/components-fixture", | ||
| "guides/auto-type-table-fixture" | ||
| ] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.