Add docs route link resolution and update VueForge codeblock

KolesnikovKirill · KolesnikovKirill · commit f6e71a204d84 · 2026-06-12T22:59:37.000+07:00
diff --git a/apps/demo/package.json b/apps/demo/package.json
@@ -16,8 +16,8 @@
   },
   "dependencies": {
     "@codemonster-ru/vue-codeblock": "^2.2.0",
-    "@codemonster-ru/vue-ssg-core": "^2.0.4",
-    "@codemonster-ru/vueforge-codeblock": "^3.4.2",
+    "@codemonster-ru/vue-ssg-core": "^2.1.0",
+    "@codemonster-ru/vueforge-codeblock": "^3.5.0",
     "@codemonster-ru/vueforge-core": "^1.22.2",
     "@codemonster-ru/vueforge-icons": "^1.4.0",
     "@codemonster-ru/vueforge-layouts": "^1.13.2",
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/create-vue-ssg/CHANGELOG.md b/packages/create-vue-ssg/CHANGELOG.md
@@ -2,6 +2,15 @@
 
 <!-- markdownlint-disable MD024 -->
 
+## 2.0.7 - 2026-06-12
+
+### Patch Changes
+
+- Update generated templates to depend on
+  `@codemonster-ru/vue-ssg-core@^2.1.0`.
+- Update the generated docs template to depend on
+  `@codemonster-ru/vueforge-codeblock@^3.5.0`.
+
 ## 2.0.6 - 2026-06-03
 
 ### Patch Changes
diff --git a/packages/create-vue-ssg/package.json b/packages/create-vue-ssg/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@codemonster-ru/create-vue-ssg",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Scaffold a Codemonster SSG project.",
   "keywords": [
     "create",
diff --git a/packages/create-vue-ssg/templates/default/package.json b/packages/create-vue-ssg/templates/default/package.json
@@ -11,7 +11,7 @@
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
-    "@codemonster-ru/vue-ssg-core": "^2.0.4",
+    "@codemonster-ru/vue-ssg-core": "^2.1.0",
     "vite-ssg": "^28.3.0",
     "vue": "^3.5.13",
     "vue-router": "^5.0.4"
diff --git a/packages/create-vue-ssg/templates/docs/package.json b/packages/create-vue-ssg/templates/docs/package.json
@@ -15,8 +15,8 @@
     "check": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@codemonster-ru/vue-ssg-core": "^2.0.4",
-    "@codemonster-ru/vueforge-codeblock": "^3.4.2",
+    "@codemonster-ru/vue-ssg-core": "^2.1.0",
+    "@codemonster-ru/vueforge-codeblock": "^3.5.0",
     "@codemonster-ru/vueforge-core": "^1.22.2",
     "@codemonster-ru/vueforge-icons": "^1.4.0",
     "@codemonster-ru/vueforge-layouts": "^1.13.2",
diff --git a/packages/vue-ssg-core/CHANGELOG.md b/packages/vue-ssg-core/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 <!-- markdownlint-disable MD024 -->
 
+## 2.1.0 - 2026-06-12
+
+### Minor Changes
+
+- Add the public `resolveDocsRouteHref` helper for resolving relative Markdown
+  links against the current docs route, normalizing `.md`/`.mdx` targets, and
+  rejecting external or non-navigation URLs.
+
 ## 2.0.4 - 2026-06-03
 
 ### Patch Changes
diff --git a/packages/vue-ssg-core/package.json b/packages/vue-ssg-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@codemonster-ru/vue-ssg-core",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Core APIs for Codemonster SSG apps.",
   "keywords": [
     "vue",
diff --git a/packages/vue-ssg-core/src/docsLinks.ts b/packages/vue-ssg-core/src/docsLinks.ts
@@ -0,0 +1,33 @@
+const DOCS_URL_ORIGIN = 'https://docs.local'
+
+export function resolveDocsRouteHref(href: string, pagePath: string): string | null {
+  const normalizedHref = href.trim()
+
+  if (!normalizedHref) {
+    return null
+  }
+
+  if (normalizedHref.startsWith('#')) {
+    return normalizedHref
+  }
+
+  if (
+    normalizedHref.startsWith('//') ||
+    /^[a-z][a-z\d+.-]*:/i.test(normalizedHref)
+  ) {
+    return null
+  }
+
+  const baseUrl = new URL(pagePath, DOCS_URL_ORIGIN)
+  const targetUrl = new URL(normalizedHref, baseUrl)
+
+  if (targetUrl.origin !== DOCS_URL_ORIGIN) {
+    return null
+  }
+
+  targetUrl.pathname = targetUrl.pathname
+    .replace(/\/index\.(?:md|mdx)$/i, '/')
+    .replace(/\.(?:md|mdx)$/i, '')
+
+  return `${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`
+}
diff --git a/packages/vue-ssg-core/src/index.ts b/packages/vue-ssg-core/src/index.ts
@@ -21,6 +21,7 @@ export {
   createDocsRoutesFromManifest,
   type CreateDocsRoutesFromManifestInput
 } from './routes'
+export { resolveDocsRouteHref } from './docsLinks'
 export {
   defineDocsConfig,
   type DocsAsideProps,
diff --git a/packages/vue-ssg-core/test/docsLinks.test.mjs b/packages/vue-ssg-core/test/docsLinks.test.mjs
@@ -0,0 +1,55 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveDocsRouteHref } from '../dist/index.js'
+
+test('resolves relative docs links from the current page route', () => {
+  assert.equal(
+    resolveDocsRouteHref('installation', '/annabel/getting-started'),
+    '/annabel/installation'
+  )
+  assert.equal(
+    resolveDocsRouteHref('../configuration', '/annabel/basics/routing'),
+    '/annabel/configuration'
+  )
+})
+
+test('preserves query and hash fragments', () => {
+  assert.equal(
+    resolveDocsRouteHref('./api.md?mode=full#usage', '/annabel/getting-started'),
+    '/annabel/api?mode=full#usage'
+  )
+  assert.equal(resolveDocsRouteHref('#usage', '/annabel/getting-started'), '#usage')
+})
+
+test('normalizes index markdown links to directory routes', () => {
+  assert.equal(
+    resolveDocsRouteHref('./index.md', '/annabel/getting-started'),
+    '/annabel/'
+  )
+  assert.equal(
+    resolveDocsRouteHref('../guide/index.mdx', '/annabel/basics/routing'),
+    '/annabel/guide/'
+  )
+})
+
+test('keeps absolute application routes inside the router', () => {
+  assert.equal(
+    resolveDocsRouteHref('/vueforge-core/components/button', '/annabel/getting-started'),
+    '/vueforge-core/components/button'
+  )
+})
+
+test('rejects external and non-navigation links', () => {
+  assert.equal(resolveDocsRouteHref('https://example.com/docs.md', '/annabel/getting-started'), null)
+  assert.equal(
+    resolveDocsRouteHref(' https://example.com/docs.md ', '/annabel/getting-started'),
+    null
+  )
+  assert.equal(resolveDocsRouteHref('//example.com/docs.md', '/annabel/getting-started'), null)
+  assert.equal(resolveDocsRouteHref('\\\\example.com/docs.md', '/annabel/getting-started'), null)
+  assert.equal(resolveDocsRouteHref('mailto:test@example.com', '/annabel/getting-started'), null)
+  assert.equal(resolveDocsRouteHref('tel:+123', '/annabel/getting-started'), null)
+  assert.equal(resolveDocsRouteHref('', '/annabel/getting-started'), null)
+  assert.equal(resolveDocsRouteHref('   ', '/annabel/getting-started'), null)
+})

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@codemonster-ru/create-vue-ssg",`
`3`		`- "version": "2.0.6",`
	`3`	`+ "version": "2.0.7",`
`4`	`4`	`"description": "Scaffold a Codemonster SSG project.",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"create",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@codemonster-ru/vue-ssg-core",`
`3`		`- "version": "2.0.4",`
	`3`	`+ "version": "2.1.0",`
`4`	`4`	`"description": "Core APIs for Codemonster SSG apps.",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"vue",`