@lexibase/rdx-core 2.1.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,10 @@
1
+ import {
2
+ DEFAULT_POSITION,
3
+ documentExtension,
4
+ orderedName,
5
+ slugFromRelativePath
6
+ } from "./chunk-L7FZDK6G.js";
7
+
1
8
  // src/content/static-source.ts
2
9
  import matter from "gray-matter";
3
10
  function parseStaticDocument(source) {
@@ -16,8 +23,6 @@ function parseStaticDocument(source) {
16
23
  import fs from "fs";
17
24
  import path from "path";
18
25
  import matter2 from "gray-matter";
19
- var MDX_EXTENSION = ".mdx";
20
- var DEFAULT_POSITION = Number.MAX_SAFE_INTEGER;
21
26
  function getDocsRoot(docsDir = "docs") {
22
27
  return path.resolve(
23
28
  /* turbopackIgnore: true */
@@ -37,35 +42,61 @@ function stringValue(value, fallback) {
37
42
  function numberValue(value, fallback = DEFAULT_POSITION) {
38
43
  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
39
44
  }
40
- function readCategoryMeta(categoryPath, fallbackTitle) {
45
+ function readCategoryMeta(categoryPath, fallbackTitle, position = DEFAULT_POSITION) {
41
46
  const metaPath = path.join(categoryPath, "_category.json");
42
- if (!fs.existsSync(metaPath)) {
43
- return { title: fallbackTitle, position: DEFAULT_POSITION };
47
+ if (!fs.existsSync(
48
+ /* turbopackIgnore: true */
49
+ metaPath
50
+ )) {
51
+ return { title: fallbackTitle, position };
44
52
  }
45
53
  try {
46
- const parsed = JSON.parse(fs.readFileSync(metaPath, "utf8"));
54
+ const parsed = JSON.parse(
55
+ fs.readFileSync(
56
+ /* turbopackIgnore: true */
57
+ metaPath,
58
+ "utf8"
59
+ )
60
+ );
47
61
  if (!isRecord(parsed)) {
48
- return { title: fallbackTitle, position: DEFAULT_POSITION };
62
+ return { title: fallbackTitle, position };
49
63
  }
50
64
  return {
51
65
  title: stringValue(parsed.title, fallbackTitle),
52
- position: numberValue(parsed.sidebar_position)
66
+ position: numberValue(parsed.sidebar_position, position)
53
67
  };
54
68
  } catch {
55
- return { title: fallbackTitle, position: DEFAULT_POSITION };
69
+ return { title: fallbackTitle, position };
56
70
  }
57
71
  }
58
- function findMdxFiles(directory) {
59
- const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
72
+ function findDocumentFiles(directory) {
73
+ const entries = fs.readdirSync(
74
+ /* turbopackIgnore: true */
75
+ directory,
76
+ { withFileTypes: true }
77
+ ).sort((a, b) => a.name.localeCompare(b.name));
60
78
  return entries.flatMap((entry) => {
61
79
  const entryPath = path.join(directory, entry.name);
62
- if (entry.isDirectory()) return findMdxFiles(entryPath);
63
- if (entry.isFile() && entry.name.endsWith(MDX_EXTENSION)) return [entryPath];
80
+ if (entry.isDirectory()) return findDocumentFiles(entryPath);
81
+ if (entry.isFile() && documentExtension.test(entry.name)) return [entryPath];
64
82
  return [];
65
83
  });
66
84
  }
67
- function slugFromRelativePath(relativePath) {
68
- return relativePath.split(path.sep).join("/").replace(/\.mdx$/, "");
85
+ function matchingEntries(directory, name, folders) {
86
+ if (!fs.existsSync(
87
+ /* turbopackIgnore: true */
88
+ directory
89
+ )) return [];
90
+ return fs.readdirSync(
91
+ /* turbopackIgnore: true */
92
+ directory,
93
+ { withFileTypes: true }
94
+ ).flatMap((entry) => {
95
+ if (folders ? !entry.isDirectory() : !entry.isFile() || !documentExtension.test(entry.name))
96
+ return [];
97
+ const candidate = folders ? entry.name : entry.name.replace(documentExtension, "");
98
+ return orderedName(candidate).name === name ? [path.join(directory, entry.name)] : [];
99
+ });
69
100
  }
70
101
  function isSafeSlug(slug) {
71
102
  if (path.isAbsolute(slug) || slug.includes("\\")) return false;
@@ -82,13 +113,11 @@ function getDocsIndex({ docsDir, fallbackDocsDir, fallbackOnly } = {}, onError)
82
113
  (category) => category.pages.map((page) => [page.slug, page])
83
114
  )
84
115
  );
116
+ const translatedRoot = getDocsRoot(docsDir);
85
117
  return primary.map((category) => ({
86
118
  ...category,
87
119
  title: readCategoryMeta(
88
- path.join(
89
- getDocsRoot(docsDir),
90
- category.id === "_root" ? "" : category.id
91
- ),
120
+ category.id === "_root" ? translatedRoot : matchingEntries(translatedRoot, category.id, true)[0] ?? path.join(translatedRoot, category.id),
92
121
  category.title
93
122
  ).title,
94
123
  pages: category.pages.map((page) => ({
@@ -98,17 +127,37 @@ function getDocsIndex({ docsDir, fallbackDocsDir, fallbackOnly } = {}, onError)
98
127
  }));
99
128
  }
100
129
  const docsRoot = getDocsRoot(docsDir);
101
- if (!fs.existsSync(docsRoot)) return [];
130
+ if (!fs.existsSync(
131
+ /* turbopackIgnore: true */
132
+ docsRoot
133
+ )) return [];
102
134
  const categories = /* @__PURE__ */ new Map();
103
- for (const filePath of findMdxFiles(docsRoot)) {
135
+ const slugs = /* @__PURE__ */ new Map();
136
+ for (const filePath of findDocumentFiles(docsRoot)) {
137
+ const slug = slugFromRelativePath(path.relative(docsRoot, filePath));
138
+ const previous = slugs.get(slug);
139
+ if (previous) {
140
+ const error = new Error(
141
+ `[RDX] Duplicate documentation route "${slug}": ${previous} and ${filePath}. Keep one page per route.`
142
+ );
143
+ if (!onError) throw error;
144
+ onError(error, filePath);
145
+ continue;
146
+ }
147
+ slugs.set(slug, filePath);
104
148
  const relativePath = path.relative(docsRoot, filePath);
105
149
  const pathParts = relativePath.split(path.sep);
106
- const categoryId = pathParts.length > 1 ? pathParts[0] ?? "_root" : "_root";
107
- const categoryPath = categoryId === "_root" ? docsRoot : path.join(docsRoot, categoryId);
150
+ const categoryFolder = pathParts.length > 1 ? pathParts[0] ?? "_root" : "_root";
151
+ const { name: categoryId, position: categoryPosition } = orderedName(categoryFolder);
152
+ const categoryPath = categoryFolder === "_root" ? docsRoot : path.join(docsRoot, categoryFolder);
108
153
  const fallbackCategoryTitle = categoryId === "_root" ? "Overview" : toTitle(categoryId);
109
154
  let category = categories.get(categoryId);
110
155
  if (!category) {
111
- const meta = readCategoryMeta(categoryPath, fallbackCategoryTitle);
156
+ const meta = readCategoryMeta(
157
+ categoryPath,
158
+ fallbackCategoryTitle,
159
+ categoryPosition
160
+ );
112
161
  const createdCategory = {
113
162
  id: categoryId,
114
163
  title: meta.title,
@@ -121,20 +170,31 @@ function getDocsIndex({ docsDir, fallbackDocsDir, fallbackOnly } = {}, onError)
121
170
  }
122
171
  let frontmatter = {};
123
172
  try {
124
- const raw = fs.readFileSync(filePath, "utf8");
173
+ const raw = fs.readFileSync(
174
+ /* turbopackIgnore: true */
175
+ filePath,
176
+ "utf8"
177
+ );
125
178
  const parsed = onError ? parseStaticDocument(raw) : matter2(raw);
126
179
  frontmatter = isRecord(parsed.data) ? parsed.data : {};
127
180
  } catch (error) {
128
181
  if (!onError) throw error;
129
182
  onError(error, filePath);
130
183
  }
131
- const slug = slugFromRelativePath(relativePath);
132
184
  const fallbackTitle = toTitle(path.basename(slug));
185
+ const navTitle = stringValue(frontmatter.navTitle, "");
186
+ const filePosition = orderedName(
187
+ path.basename(relativePath).replace(documentExtension, "")
188
+ ).position;
133
189
  category.pages.push({
134
190
  slug,
135
191
  title: stringValue(frontmatter.title, fallbackTitle),
192
+ ...navTitle ? { navTitle } : {},
136
193
  description: stringValue(frontmatter.description, ""),
137
- position: numberValue(frontmatter.link_position),
194
+ position: numberValue(
195
+ frontmatter.order,
196
+ numberValue(frontmatter.link_position, filePosition)
197
+ ),
138
198
  sourcePath: filePath
139
199
  });
140
200
  }
@@ -157,15 +217,32 @@ function getDocument(slug, { docsDir, fallbackDocsDir, fallbackOnly } = {}) {
157
217
  if (fallbackOnly)
158
218
  return getDocument(slug, { docsDir: fallbackDocsDir ?? docsDir });
159
219
  const docsRoot = getDocsRoot(docsDir);
160
- const sourcePath = path.resolve(docsRoot, `${slug}${MDX_EXTENSION}`);
161
- const relativePath = path.relative(docsRoot, sourcePath);
162
- if (relativePath.startsWith("..") || path.isAbsolute(relativePath))
163
- return null;
220
+ const parts = slug.split("/");
221
+ const name = parts.pop();
222
+ let directories = [docsRoot];
223
+ for (const part of parts)
224
+ directories = directories.flatMap(
225
+ (directory) => matchingEntries(directory, part, true)
226
+ );
227
+ const candidates = directories.flatMap(
228
+ (directory) => matchingEntries(directory, name, false)
229
+ );
230
+ if (candidates.length > 1)
231
+ throw new Error(
232
+ `[RDX] Duplicate documentation route "${slug}": ${candidates.join(" and ")}. Keep one page per route.`
233
+ );
164
234
  if (fallbackDocsDir && !getDocument(slug, { docsDir: fallbackDocsDir }))
165
235
  return null;
166
- if (!fs.existsSync(sourcePath))
236
+ const sourcePath = candidates[0];
237
+ if (!sourcePath)
167
238
  return fallbackDocsDir ? getDocument(slug, { docsDir: fallbackDocsDir }) : null;
168
- const parsed = matter2(fs.readFileSync(sourcePath, "utf8"));
239
+ const parsed = matter2(
240
+ fs.readFileSync(
241
+ /* turbopackIgnore: true */
242
+ sourcePath,
243
+ "utf8"
244
+ )
245
+ );
169
246
  return {
170
247
  slug,
171
248
  sourcePath,
@@ -1,5 +1,19 @@
1
1
  // src/content/document-links.ts
2
+ import path2 from "path";
3
+
4
+ // src/content/filenames.ts
2
5
  import path from "path";
6
+ var documentExtension = /\.mdx?$/;
7
+ var DEFAULT_POSITION = Number.MAX_SAFE_INTEGER;
8
+ function orderedName(name) {
9
+ const match = /^(\d{2})-(.+)$/.exec(name);
10
+ return match && match[2] !== "." && match[2] !== ".." ? { name: match[2], position: Number(match[1]) } : { name, position: DEFAULT_POSITION };
11
+ }
12
+ function slugFromRelativePath(relativePath) {
13
+ return relativePath.replace(documentExtension, "").split(path.sep).map((segment) => orderedName(segment).name).join("/");
14
+ }
15
+
16
+ // src/content/document-links.ts
3
17
  var RdxDocumentLinkError = class extends Error {
4
18
  constructor(sourcePath, href, reason) {
5
19
  super(`[RDX] Invalid document link "${href}" in ${sourcePath}: ${reason}`);
@@ -9,12 +23,20 @@ var RdxDocumentLinkError = class extends Error {
9
23
  reason;
10
24
  };
11
25
  function createDocumentLinkResolver(options) {
12
- const root = path.resolve(options.sourceRoot);
13
- const current = path.resolve(options.sourcePath);
26
+ const root = path2.resolve(options.sourceRoot);
27
+ const current = path2.resolve(options.sourcePath);
14
28
  const documents = new Map(
15
29
  options.documents.flatMap((page) => [
16
- [path.resolve(page.sourcePath), page.slug],
17
- ...options.virtualPaths ? [[path.resolve(root, `${page.slug}.mdx`), page.slug]] : []
30
+ [path2.resolve(page.sourcePath), page.slug],
31
+ ...options.virtualPaths ? [
32
+ [
33
+ path2.resolve(
34
+ root,
35
+ `${page.slug}${path2.extname(page.sourcePath)}`
36
+ ),
37
+ page.slug
38
+ ]
39
+ ] : []
18
40
  ])
19
41
  );
20
42
  const routeCounts = /* @__PURE__ */ new Map();
@@ -29,7 +51,7 @@ function createDocumentLinkResolver(options) {
29
51
  try {
30
52
  decoded = decodeURIComponent(pathname);
31
53
  } catch {
32
- if (/\.mdx$/i.test(pathname))
54
+ if (/\.mdx?$/i.test(pathname))
33
55
  throw new RdxDocumentLinkError(
34
56
  current,
35
57
  href,
@@ -37,22 +59,27 @@ function createDocumentLinkResolver(options) {
37
59
  );
38
60
  return href;
39
61
  }
40
- if (!decoded.endsWith(".mdx")) return href;
62
+ if (!/\.mdx?$/.test(decoded)) return href;
41
63
  const fail = (reason) => {
42
64
  throw new RdxDocumentLinkError(current, href, reason);
43
65
  };
44
- if (path.isAbsolute(decoded) || decoded.includes("\\") || decoded.includes("\0"))
66
+ if (path2.isAbsolute(decoded) || decoded.includes("\\") || decoded.includes("\0"))
45
67
  fail("use forward-slash relative paths without null characters.");
46
- const target = path.resolve(path.dirname(current), decoded);
47
- const relative = path.relative(root, target);
48
- if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
68
+ const target = path2.resolve(path2.dirname(current), decoded);
69
+ const relative = path2.relative(root, target);
70
+ if (relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative))
49
71
  fail("the destination escapes this documentation source.");
50
- const slug = documents.get(target) ?? fail(
72
+ const slug = documents.get(target) ?? (options.virtualPaths ? documents.get(
73
+ path2.resolve(
74
+ root,
75
+ `${slugFromRelativePath(relative)}${path2.extname(relative)}`
76
+ )
77
+ ) : void 0) ?? fail(
51
78
  `"${relative}" does not exist in this documentation source${options.routePrefix ? ` (${options.routePrefix})` : ""}.`
52
79
  );
53
80
  if ((routeCounts.get(slug) ?? 0) > 1)
54
81
  fail("the destination has an ambiguous documentation route.");
55
- const route = [
82
+ const route = options.documentHref?.(slug) ?? [
56
83
  options.basePath ?? "/docs",
57
84
  options.routePrefix && encodeURIComponent(options.routePrefix),
58
85
  ...slug.split("/").map(encodeURIComponent)
@@ -106,6 +133,10 @@ function remarkDocumentLinks(options) {
106
133
  }
107
134
 
108
135
  export {
136
+ documentExtension,
137
+ DEFAULT_POSITION,
138
+ orderedName,
139
+ slugFromRelativePath,
109
140
  RdxDocumentLinkError,
110
141
  createDocumentLinkResolver,
111
142
  remarkDocumentLinks
@@ -1,2 +1,2 @@
1
1
  import '@lexibase/rdx-types';
2
- export { R as RdxConfigError, h as collectSnapshotContributions, c as createRdxProject, d as defineConfig, g as getContentSources, n as normalizeLocalization, r as resolveConfig, f as resolveProjectPath } from '../index-DjuvW7o_.js';
2
+ export { R as RdxConfigError, h as collectSnapshotContributions, c as createRdxProject, d as defineConfig, g as getContentSources, j as getEditPageHref, n as normalizeLocalization, r as resolveConfig, f as resolveProjectPath } from '../index-2qiAhOwp.js';
@@ -3,10 +3,11 @@ import {
3
3
  collectSnapshotContributions,
4
4
  createRdxProject,
5
5
  defineConfig,
6
+ getEditPageHref,
6
7
  normalizeLocalization,
7
8
  resolveConfig,
8
9
  resolveProjectPath
9
- } from "../chunk-WDWRIRH2.js";
10
+ } from "../chunk-GSIKV6MV.js";
10
11
  import {
11
12
  getContentSources
12
13
  } from "../chunk-SNNEXRLQ.js";
@@ -16,6 +17,7 @@ export {
16
17
  createRdxProject,
17
18
  defineConfig,
18
19
  getContentSources,
20
+ getEditPageHref,
19
21
  normalizeLocalization,
20
22
  resolveConfig,
21
23
  resolveProjectPath
@@ -9,12 +9,13 @@ interface DocumentLinkOptions {
9
9
  sourcePath: string;
10
10
  slug: string;
11
11
  }[];
12
+ documentHref?: (slug: string) => string;
12
13
  }
13
14
  declare class RdxDocumentLinkError extends Error {
14
15
  readonly reason: string;
15
16
  constructor(sourcePath: string, href: string, reason: string);
16
17
  }
17
- /** Resolve only explicit relative MDX links within the current content source. */
18
+ /** Resolve only explicit relative Markdown links within the current content source. */
18
19
  declare function createDocumentLinkResolver(options: DocumentLinkOptions): (href: string) => string;
19
20
  /** A remark adapter shared by generated sites and the development website. */
20
21
  declare function remarkDocumentLinks(options?: DocumentLinkOptions): ((tree: unknown) => void) | undefined;
@@ -39,6 +39,8 @@ declare function getLanguageLinks(project: RdxProject, source: RdxContentSource,
39
39
  }[];
40
40
  declare function isFallbackPage(project: RdxProject, source: RdxContentSource, sourcePath: string): boolean;
41
41
 
42
+ declare function getEditPageHref(project: Pick<RdxProject, 'config' | 'rootDir'>, source: Pick<RdxContentSource, 'id'> | undefined, sourcePath: string): string | undefined;
43
+
42
44
  declare function resolveConfig(input: unknown): ResolvedRdxConfig;
43
45
  declare function defineConfig(config: RDXConfig): RDXConfig;
44
46
  declare function createRdxProject(input: unknown, { rootDir, command, }?: {
@@ -46,4 +48,4 @@ declare function createRdxProject(input: unknown, { rootDir, command, }?: {
46
48
  command?: string;
47
49
  }): Promise<RdxProject>;
48
50
 
49
- export { RdxConfigError as R, getDocsHref as a, getLanguageLinks as b, createRdxProject as c, defineConfig as d, getLocalizedProject as e, resolveProjectPath as f, getContentSources as g, collectSnapshotContributions as h, isFallbackPage as i, normalizeLocalization as n, resolveConfig as r };
51
+ export { RdxConfigError as R, getDocsHref as a, getLanguageLinks as b, createRdxProject as c, defineConfig as d, getLocalizedProject as e, resolveProjectPath as f, getContentSources as g, collectSnapshotContributions as h, isFallbackPage as i, getEditPageHref as j, normalizeLocalization as n, resolveConfig as r };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as _lexibase_rdx_types from '@lexibase/rdx-types';
2
2
  import { RdxDocsOptions, RdxDocCategory, RdxDocument, RdxProject, RdxContentSource } from '@lexibase/rdx-types';
3
- export { R as RdxConfigError, c as createRdxProject, d as defineConfig, g as getContentSources, a as getDocsHref, b as getLanguageLinks, e as getLocalizedProject, i as isFallbackPage, r as resolveConfig, f as resolveProjectPath } from './index-DjuvW7o_.js';
4
- export { D as DocumentLinkOptions, R as RdxDocumentLinkError, c as createDocumentLinkResolver } from './document-links-Dr4JVYuN.js';
3
+ export { R as RdxConfigError, c as createRdxProject, d as defineConfig, g as getContentSources, a as getDocsHref, b as getLanguageLinks, e as getLocalizedProject, i as isFallbackPage, r as resolveConfig, f as resolveProjectPath } from './index-2qiAhOwp.js';
4
+ export { D as DocumentLinkOptions, R as RdxDocumentLinkError, c as createDocumentLinkResolver } from './document-links-fo6ul9xz.js';
5
5
 
6
6
  /**
7
7
  * Reads the documentation tree from the user's project. The URL slug always
package/dist/index.js CHANGED
@@ -5,14 +5,14 @@ import {
5
5
  getProjectDocsPaths,
6
6
  getSourceOptions,
7
7
  resolveDocsRoute
8
- } from "./chunk-CGOXC3S6.js";
8
+ } from "./chunk-GBW4LSBN.js";
9
9
  import {
10
10
  RdxConfigError,
11
11
  createRdxProject,
12
12
  defineConfig,
13
13
  resolveConfig,
14
14
  resolveProjectPath
15
- } from "./chunk-WDWRIRH2.js";
15
+ } from "./chunk-GSIKV6MV.js";
16
16
  import {
17
17
  getContentSources,
18
18
  getDocsHref,
@@ -23,7 +23,7 @@ import {
23
23
  import {
24
24
  RdxDocumentLinkError,
25
25
  createDocumentLinkResolver
26
- } from "./chunk-LCBSNAUH.js";
26
+ } from "./chunk-L7FZDK6G.js";
27
27
  export {
28
28
  RdxConfigError,
29
29
  RdxDocumentLinkError,
@@ -1,4 +1,5 @@
1
- export { D as DocumentLinkOptions, r as remarkDocumentLinks } from '../document-links-Dr4JVYuN.js';
1
+ import { D as DocumentLinkOptions } from '../document-links-fo6ul9xz.js';
2
+ export { r as remarkDocumentLinks } from '../document-links-fo6ul9xz.js';
2
3
  export { default as rehypeDocumentationHeadings } from 'rehype-slug';
3
4
  import rehypeShiki from '@shikijs/rehype';
4
5
  import remarkDirective from 'remark-directive';
@@ -11,4 +12,7 @@ declare function remarkDocumentationComponents(this: ThisParameterType<typeof re
11
12
  value: unknown;
12
13
  }) => void;
13
14
 
14
- export { rehypeDocumentationCode, remarkDocumentationComponents };
15
+ /** Serialize document content without evaluating or publishing MDX JavaScript. */
16
+ declare function exportMarkdownBody(content: string, links: DocumentLinkOptions): string;
17
+
18
+ export { DocumentLinkOptions, exportMarkdownBody, rehypeDocumentationCode, remarkDocumentationComponents };