@docubook/core 1.1.0 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wildan Nursahidan
+
+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

@@ -32,32 +32,118 @@ Bun (independent runtime/package manager):
 bun add @docubook/core
 ```
 
-## Dependency Management Policy
+## Usage
 
-Dependencies required for markdown processing are managed in this package and updated by the DocuBook author.
+### Quick Start (Recommended)
 
-This means app-level users should focus on content and integration. Plugin upgrades, compatibility checks, and pipeline maintenance are handled centrally by DocuBook.
+```ts
+import { cache } from "react";
+import { createMdxContentService } from "@docubook/core";
 
-### Managed Markdown Dependencies
+type Frontmatter = {
+  title: string;
+  description: string;
+  image: string;
+  date: string;
+};
 
-- gray-matter
-- rehype-autolink-headings
-- rehype-code-titles
-- rehype-prism-plus
-- rehype-slug
-- remark-gfm
-- unist-util-visit
+type TocItem = {
+  level: number;
+  text: string;
+  href: string;
+};
 
-The most important part is the `remark` and `rehype` plugin stack, which is intentionally owned by this package to avoid dependency drift across apps.
+const components = {
+  // your MDX components
+};
 
-## Why This Matters
+const docsService = createMdxContentService<Frontmatter, TocItem>({
+  parseOptions: { components },
+  cacheFn: cache,
+});
 
-- Consistent behavior across all DocuBook-based projects
-- Easier maintenance and safer upgrades
-- Less dependency duplication in app-level package.json files
-- Faster onboarding for users who only need to write docs
+const doc = await docsService.getCompiledForSlug("getting-started/introduction");
+const frontmatter = await docsService.getFrontmatterForSlug("getting-started/introduction");
+const tocs = await docsService.getTocsForSlug("getting-started/introduction");
+```
 
-## Usage
+### Importable APIs and What They Do
+
+#### Runtime APIs
+
+- `parseMdx`: Compile raw MDX string with optional custom parse options. Returns `MdxCompileResult<Frontmatter>`.
+- `createMdxContentService`: Create slug-based docs service (`getParsedForSlug`, `getCompiledForSlug`, `getFrontmatterForSlug`, `getTocsForSlug`). Returns a service object.
+- `readMdxFileBySlug`: Read `slug.mdx` or `slug/index.mdx` from docs directory. Returns `ReadMdxFileResult`.
+- `parseMdxFile`: Convert raw file result into `frontmatter`, `tocs`, `content`, `filePath`. Returns `ParsedMdxFile<Frontmatter, TocItem>`.
+- `compileParsedMdxFile`: Compile parsed MDX while preserving metadata and TOCs. Returns `CompiledMdxFile<Frontmatter, TocItem>`.
+- `extractFrontmatter`: Parse frontmatter only from raw markdown/MDX. Returns `Frontmatter`.
+- `extractTocsFromRawMdx`: Extract headings for table of contents generation. Returns `TocItem[]`.
+- `sluggify`: Convert heading text into URL-safe slug. Returns `string`.
+- `createDefaultRehypePlugins`: Get default DocuBook rehype plugin stack. Returns `unknown[]`.
+- `createDefaultRemarkPlugins`: Get default DocuBook remark plugin stack. Returns `unknown[]`.
+- `preProcess`: Add pre-processing behavior for code blocks (advanced customization). Returns a transformer function.
+- `postProcess`: Add post-processing behavior for code blocks (advanced customization). Returns a transformer function.
+- `handleCodeTitles`: Move code title metadata to `<pre>` attributes (advanced customization). Returns a transformer function.
+
+#### Type Exports
+
+|               Type               |                    Purpose                    |
+| -------------------------------- | --------------------------------------------- |
+| `MdxCompileResult`               | Result shape for compiled MDX content         |
+| `TocItem`                        | Heading item structure used by TOC extraction |
+| `ParseMdxOptions`                | Options for `parseMdx` compile behavior       |
+| `ReadMdxFileResult`              | Return type for `readMdxFileBySlug`           |
+| `ParsedMdxFile`                  | Parsed file structure before compile          |
+| `CompiledMdxFile`                | Compiled file structure with metadata and TOC |
+| `CreateMdxContentServiceOptions` | Options for creating the content service      |
+
+### Quick Import Recipes
+
+#### 1. Compile raw MDX only
+
+```ts
+import { parseMdx } from "@docubook/core";
+```
+
+Use this when your source is already in memory and you only need compiled content.
+
+#### 2. Read frontmatter only
+
+```ts
+import { extractFrontmatter } from "@docubook/core";
+```
+
+Use this for metadata pages where full MDX compilation is unnecessary.
+
+#### 3. Build TOC from raw content
+
+```ts
+import { extractTocsFromRawMdx } from "@docubook/core";
+```
+
+Use this when you need heading navigation from markdown/MDX text.
+
+#### 4. Slug-based docs service (recommended for app integration)
+
+```ts
+import { createMdxContentService } from "@docubook/core";
+```
+
+Use this as the default app-level integration for frontmatter, TOC, and compiled docs in one service.
+
+#### 5. Low-level file pipeline (advanced)
+
+```ts
+import {
+  readMdxFileBySlug,
+  parseMdxFile,
+  compileParsedMdxFile,
+} from "@docubook/core";
+```
+
+Use this when you need full control over each pipeline step.
+
+### Basic Compile Helpers
 
 ```ts
 import {
@@ -109,20 +195,38 @@ const docsService = createMdxContentService<Frontmatter>({
 const doc = await docsService.getCompiledForSlug("getting-started/introduction");
 ```
 
-## API Overview
+## Dependency Management Policy
 
-- `parseMdx` - Compiles raw MDX with default or custom plugin options
-- `createMdxContentService` - Unified high-level API for read/parse/compile/getters
-- `readMdxFileBySlug` - Reads `slug.mdx` or `slug/index.mdx` from docs directory
-- `parseMdxFile` - Converts raw file result into `frontmatter` + `tocs` + `content`
-- `compileParsedMdxFile` - Compiles a parsed document while preserving metadata
-- `extractFrontmatter` - Parses frontmatter from raw markdown/MDX
-- `extractTocsFromRawMdx` - Extracts headings for TOC generation
-- `sluggify` - Converts heading text into URL-friendly slugs
+Dependencies required for markdown processing are managed in this package and updated by the DocuBook author.
+
+This means app-level users should focus on content and integration. Plugin upgrades, compatibility checks, and pipeline maintenance are handled centrally by DocuBook.
+
+### Managed Markdown Dependencies
+
+- gray-matter
+- rehype-autolink-headings
+- rehype-code-titles
+- rehype-prism-plus
+- rehype-slug
+- remark-gfm
+- unist-util-visit
+
+The `remark` and `rehype` plugin stack is intentionally owned by this package to avoid dependency drift across apps.
+
+## Why This Matters
+
+- Consistent behavior across all DocuBook-based projects
+- Easier maintenance and safer upgrades
+- Less dependency duplication in app-level package.json files
+- Faster onboarding for users who only need to write docs
 
 ## Notes
 
-If your app uses `next-mdx-remote` directly for rendering in custom components, keep that direct dependency in the app.
+`@docubook/core` already includes and manages the MDX runtime/compile dependencies (including `next-mdx-remote`) as part of the package contract.
+
+In most integrations, users only need to install `@docubook/core` and use the core APIs.
+
+Only add `next-mdx-remote` directly in your app if your app explicitly imports it in app-level code.
 
 For compile pipeline plugins (especially `remark` and `rehype` plugins), rely on this package and avoid re-declaring them at app level unless you have a specific override requirement.
 

package/dist/extract.js

@@ -5,7 +5,7 @@ export function sluggify(text) {
 }
 export function extractTocsFromRawMdx(rawMdx) {
     // Match code blocks, markdown headings, and <Release version="x.y.z" />.
-    const combinedRegex = /(```[\s\S]*?```)|^(#{2,4})\s(.+)$|<Release[^>]*version="([^"]+)"/gm;
+    const combinedRegex = /(```[\s\S]*?```)|^(#{2,4})\s(.+)$|<Release\s+version="([^"]+)"/gm;
     const extractedHeadings = [];
     let match;
     while ((match = combinedRegex.exec(rawMdx)) !== null) {

package/dist/extract.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC,MAAM,UAAU,QAAQ,CAAC,IAAY;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAChD,yEAAyE;IACzE,MAAM,aAAa,GAAG,oEAAoE,CAAC;IAC3F,MAAM,iBAAiB,GAAc,EAAE,CAAC;IAExC,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,CAAC,CAAC;YAAE,SAAS;QAEvB,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACX,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACrC,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACpC,iBAAiB,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,YAAY;gBACnB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,IAAI,QAAQ,CAAC,WAAW,CAAC,EAAE;aACpC,CAAC,CAAC;YACH,SAAS;QACb,CAAC;QAED,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,iBAAiB,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,CAAC;gBACR,IAAI,EAAE,IAAI,OAAO,EAAE;gBACnB,IAAI,EAAE,IAAI,OAAO,EAAE;aACtB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,iBAAiB,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAc,OAAe;IAC3D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,IAAmB,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC,MAAM,UAAU,QAAQ,CAAC,IAAY;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAChD,yEAAyE;IACzE,MAAM,aAAa,GAAG,kEAAkE,CAAC;IACzF,MAAM,iBAAiB,GAAc,EAAE,CAAC;IAExC,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,CAAC,CAAC;YAAE,SAAS;QAEvB,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACX,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACrC,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACpC,iBAAiB,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,YAAY;gBACnB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,IAAI,QAAQ,CAAC,WAAW,CAAC,EAAE;aACpC,CAAC,CAAC;YACH,SAAS;QACb,CAAC;QAED,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,iBAAiB,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,CAAC;gBACR,IAAI,EAAE,IAAI,OAAO,EAAE;gBACnB,IAAI,EAAE,IAAI,OAAO,EAAE;aACtB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,iBAAiB,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAc,OAAe;IAC3D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,IAAmB,CAAC;AAC/C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@docubook/core",
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "Shared MDX compile pipeline and markdown utilities for DocuBook",
     "type": "module",
     "main": "./dist/index.js",
@@ -30,7 +30,10 @@
     "homepage": "https://docubook.pro/",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/DocuBook/docubook"
+        "url": "git+https://github.com/DocuBook/docubook.git"
+    },
+    "publishConfig": {
+        "access": "public"
     },
     "author": "wildan.nrs",
     "author-url": "https://wildan.dev",