Skip to content

Commit

Permalink
docs: support generating sidebar items with tags (medusajs#10672)
Browse files Browse the repository at this point in the history
* docs: support generating sidebar items with tags

* small fix

* fix dependencies

* test

* test fix

* test fix

* test fix

* test fix

* another fix

* revert change

* fix for resources
  • Loading branch information
shahednasser authored Dec 19, 2024
1 parent 1118e35 commit 65007c4
Show file tree
Hide file tree
Showing 19 changed files with 119 additions and 54 deletions.
1 change: 1 addition & 0 deletions www/apps/book/.vercelignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../../utils
6 changes: 6 additions & 0 deletions www/apps/book/next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,12 @@ const nextConfig = {
}
},
redirects,
experimental: {
outputFileTracingExcludes: {
"*": ["node_modules/@medusajs/icons"],
},
},
optimizePackageImports: ["@medusajs/icons", "@medusajs/ui"],
}

export default withMDX(nextConfig)
16 changes: 6 additions & 10 deletions www/apps/resources/next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -126,16 +126,12 @@ const nextConfig = {
},
]
},
// Redirects shouldn't be necessary anymore since we have remark / rehype
// plugins that fix links. But leaving this here in case we need it again.
// async redirects() {
// // redirect original file paths to the rewrite
// return slugChanges.map((item) => ({
// source: item.origSlug,
// destination: item.newSlug,
// permanent: true,
// }))
// },
experimental: {
outputFileTracingExcludes: {
"*": ["node_modules/@medusajs/icons"],
},
},
optimizePackageImports: ["@medusajs/icons", "@medusajs/ui"],
}

const withBundleAnalyzer = bundleAnalyzer({
Expand Down
2 changes: 1 addition & 1 deletion www/apps/resources/scripts/prepare.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ import { sidebar } from "../sidebar.mjs"
import path from "path"

async function main() {
await generateTags(path.resolve("..", "..", "packages", "tags"))
await generateSidebar(sidebar)
await generateSlugChanges()
await generateFilesMap()
await generateEditedDates()
await generateTags(path.resolve("..", "..", "packages", "tags"))
}

void main()
2 changes: 1 addition & 1 deletion www/apps/resources/utils/get-slugs.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { statSync, readdirSync } from "fs"
import path from "path"
import { getFileSlug } from "../../../packages/docs-utils/dist"
import { getFileSlug } from "docs-utils"

const monoRepoPath = path.resolve("..", "..", "..")

Expand Down
2 changes: 1 addition & 1 deletion www/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
},
"scripts": {
"build": "turbo run build",
"build:docs": "turbo run build --filter=docs-v2",
"build:docs": "turbo run build --filter=book",
"build:resources": "turbo run build --filter=resources",
"build:user-guide": "turbo run build --filter=user-guide",
"build:packages": "turbo run build --filter='./packages/*'",
Expand Down
7 changes: 5 additions & 2 deletions www/packages/build-scripts/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,19 @@
"watch": "tsc --watch"
},
"dependencies": {
"remark-rehype-plugins": "*"
"docs-utils": "*",
"tags": "*"
},
"devDependencies": {
"@types/node": "^20.11.20",
"docs-utils": "*",
"rimraf": "^5.0.5",
"tsconfig": "*",
"types": "*",
"typescript": "^5.3.3"
},
"peerDependencies": {
"docs-utils": "*"
},
"engines": {
"node": ">=18.17.0"
}
Expand Down
39 changes: 32 additions & 7 deletions www/packages/build-scripts/src/generate-sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readdirSync, statSync } from "fs"
import path from "path"
import { getSidebarItemLink, sidebarAttachHrefCommonOptions } from "./index.js"
import getCoreFlowsRefSidebarChildren from "./utils/get-core-flows-ref-sidebar-children.js"
import { parseTags } from "./utils/parse-tags.js"

export type ItemsToAdd = SidebarItem & {
sidebar_position?: number
Expand All @@ -12,7 +13,7 @@ const customGenerators: Record<string, () => Promise<ItemsToAdd[]>> = {
"core-flows": getCoreFlowsRefSidebarChildren,
}

async function getSidebarItems(
async function getAutogeneratedSidebarItems(
dir: string,
nested = false
): Promise<ItemsToAdd[]> {
Expand All @@ -32,7 +33,7 @@ async function getSidebarItems(
}

if (fileBasename !== "page.mdx" && statSync(filePath).isDirectory()) {
const newItems = await getSidebarItems(
const newItems = await getAutogeneratedSidebarItems(
filePath.replace(basePath, ""),
true
)
Expand Down Expand Up @@ -86,6 +87,26 @@ async function getSidebarItems(
return items
}

async function getAutogeneratedTagSidebarItems(
tags: string
): Promise<ItemsToAdd[]> {
const items: ItemsToAdd[] = []

const parsedTags = parseTags(tags)

items.push(
...parsedTags.map(
(tagItem) =>
({
type: "link",
...tagItem,
}) as ItemsToAdd
)
)

return sidebarAttachHrefCommonOptions(items)
}

async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
if (!item.type) {
throw new Error(
Expand All @@ -100,12 +121,16 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
return item
}
if (item.autogenerate_path) {
item.children = (await getSidebarItems(item.autogenerate_path)).map(
(child) => {
delete child.sidebar_position
item.children = (
await getAutogeneratedSidebarItems(item.autogenerate_path)
).map((child) => {
delete child.sidebar_position

return child
}
return child
})
} else if (item.autogenerate_tags) {
item.children = await getAutogeneratedTagSidebarItems(
item.autogenerate_tags
)
} else if (
item.custom_autogenerate &&
Expand Down
2 changes: 1 addition & 1 deletion www/packages/build-scripts/src/retrieve-mdx-pages.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { readdirSync } from "fs"
import path from "path"
import { getFileSlugSync } from "../../docs-utils/dist/index.js"
import { getFileSlugSync } from "docs-utils"

type Options = {
basePath: string
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { getFrontMatter, findPageTitle } from "../../../docs-utils/dist/index.js"
import { getFrontMatter, findPageTitle } from "docs-utils"
import { ItemsToAdd, sidebarAttachHrefCommonOptions } from "../index.js"
import { InteractiveSidebarItem } from "types"

Expand Down
44 changes: 44 additions & 0 deletions www/packages/build-scripts/src/utils/parse-tags.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import { getTagItems } from "tags"
import { Tag } from "types"

export const parseTags = (tagNames: string): Tag => {
const parsedTags: Tag = []
tagNames.split(",").forEach((tagName) => {
const intersectingTags = getIntersectionTags(tagName)

if (!intersectingTags.length) {
return
}

parsedTags.push(...intersectingTags)
})

return parsedTags
}

const getIntersectionTags = (tags: string): Tag => {
const tagsToIntersect: Tag[] = tags
.split("+")
.map((tagName) => getTagItems(tagName))
.filter((tag) => tag !== undefined) as Tag[]

if (!tagsToIntersect.length) {
return []
}

if (tagsToIntersect.length === 1) {
return tagsToIntersect[0]
}

return tagsToIntersect[0].filter((tagItem) => {
return tagsToIntersect
.slice(1)
.every((otherTag) =>
otherTag.some(
(otherTagItem) =>
otherTagItem.title === tagItem.title &&
otherTagItem.path === tagItem.path
)
)
})
}
11 changes: 11 additions & 0 deletions www/packages/docs-utils/src/get-file-slug-sync.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import { matter } from "vfile-matter"
import { readSync } from "to-vfile"
import { FrontMatter } from "types"

export function getFileSlugSync(filePath: string): string | undefined {
const content = readSync(filePath)

matter(content)

return ((content.data.matter as FrontMatter).slug as string) || undefined
}
11 changes: 0 additions & 11 deletions www/packages/docs-utils/src/get-file-slug.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@
import { matter } from "vfile-matter"
import { readSync } from "to-vfile"
import { FrontMatter } from "types"
import { getFrontMatter } from "./get-front-matter.js"

export async function getFileSlug(
Expand All @@ -13,11 +10,3 @@ export async function getFileSlug(
return fileFrontmatter.slug
}
}

export function getFileSlugSync(filePath: string): string | undefined {
const content = readSync(filePath)

matter(content)

return ((content.data.matter as FrontMatter).slug as string) || undefined
}
1 change: 1 addition & 0 deletions www/packages/docs-utils/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
export * from "./find-title.js"
export * from "./get-file-slug-sync.js"
export * from "./get-file-slug.js"
export * from "./get-front-matter.js"
8 changes: 1 addition & 7 deletions www/packages/remark-rehype-plugins/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -30,18 +30,12 @@
"dependencies": {
"@cloudinary/url-gen": "^1.17.0",
"docs-utils": "*",
"remark-frontmatter": "^5.0.0",
"remark-parse": "^11.0.0",
"remark-stringify": "^11.0.0",
"to-vfile": "^8.0.0",
"unified": "^11.0.4",
"unist-builder": "3.0.0",
"unist-util-visit": "4.1.2",
"vfile-matter": "^5.0.0"
"unist-util-visit": "4.1.2"
},
"devDependencies": {
"@types/node": "^20.11.20",
"docs-ui": "*",
"rimraf": "^5.0.5",
"tsconfig": "*",
"types": "*",
Expand Down
2 changes: 1 addition & 1 deletion www/packages/remark-rehype-plugins/src/utils/fix-link.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import path from "path"
import { getFileSlugSync } from "../../../docs-utils/dist/index.js"
import { getFileSlugSync } from "docs-utils"

export type FixLinkOptions = {
currentPageFilePath: string
Expand Down
6 changes: 2 additions & 4 deletions www/packages/types/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,10 @@
"@types/node": "^20.11.20",
"rimraf": "^5.0.5",
"tsconfig": "*",
"typescript": "^5.3.3"
"typescript": "^5.3.3",
"@medusajs/icons": "^2.0.0"
},
"engines": {
"node": ">=18.17.0"
},
"dependencies": {
"@medusajs/icons": "^2.0.0"
}
}
1 change: 1 addition & 0 deletions www/packages/types/src/sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ export type SidebarSectionItems = {

export type RawSidebarItem = SidebarItem & {
autogenerate_path?: string
autogenerate_tags?: string
custom_autogenerate?: string
number?: string
}
Expand Down
10 changes: 3 additions & 7 deletions www/yarn.lock
Original file line number Diff line number Diff line change
Expand Up @@ -7215,11 +7215,13 @@ __metadata:
dependencies:
"@types/node": ^20.11.20
docs-utils: "*"
remark-rehype-plugins: "*"
rimraf: ^5.0.5
tags: "*"
tsconfig: "*"
types: "*"
typescript: ^5.3.3
peerDependencies:
docs-utils: "*"
languageName: unknown
linkType: soft

Expand Down Expand Up @@ -14643,20 +14645,14 @@ __metadata:
dependencies:
"@cloudinary/url-gen": ^1.17.0
"@types/node": ^20.11.20
docs-ui: "*"
docs-utils: "*"
remark-frontmatter: ^5.0.0
remark-parse: ^11.0.0
remark-stringify: ^11.0.0
rimraf: ^5.0.5
to-vfile: ^8.0.0
tsconfig: "*"
types: "*"
typescript: ^5.3.3
unified: ^11.0.4
unist-builder: 3.0.0
unist-util-visit: 4.1.2
vfile-matter: ^5.0.0
languageName: unknown
linkType: soft

Expand Down

0 comments on commit 65007c4

Please sign in to comment.