Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add nested property to SidebarOptions #1058

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Add nested property to SidebarOptions #1058

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1fec8d2
add and document `nested`-property
Maschga Dec 27, 2024
23dfc8c
skip generating `sidebar.ts` when directory should be nested
Maschga Dec 27, 2024
fc3dd56
calculate path to directory
Maschga Dec 27, 2024
9423319
update joi
Maschga Dec 27, 2024
61fb69f
fix creating and cleaning directories
Maschga Dec 28, 2024
40078cb
add petstore_nested-demo
Maschga Dec 28, 2024
c7ca7da
fix dirName
Maschga Dec 28, 2024
61e0dbe
Add `demo/**/index.mdx`
Maschga Dec 31, 2024
c15ddc6
remove `petstore_nested` from demo
Maschga Dec 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ demo/**/*.api.mdx
demo/**/*.info.mdx
demo/**/*.tag.mdx
demo/**/*.schema.mdx
demo/**/index.mdx
demo/**/sidebar.ts
demo/**/versions.json

Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| Name | Type | Default | Description |
| -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupPathsBy` | `string` | `null` | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`. |
| `nested` | `boolean` | `false` | Whether to create a nested filesystem structure. Needs to be `true` for Docusaurus-instances [which create a sidebar automatically from the filesystem structure](https://docusaurus.io/docs/next/sidebar/autogenerated). |
| `categoryLinkSource` | `string` | `null` | Defines what source to use for rendering category link pages when grouping paths by tag. <br/><br/>The supported options are as follows: <br/><br/> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). <br/><br/>`none`: Does not create pages for categories, only groups that can be expanded/collapsed. |
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. |
| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. |
Expand Down
97 changes: 69 additions & 28 deletions packages/docusaurus-plugin-openapi-docs/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,8 +156,34 @@ export default function pluginOpenAPIDocs(
}
}

if (sidebarOptions?.nested) {
let dirNames =
sidebarOptions.groupPathsBy === "tag"
? tags[0].map((tag) => {
return tag.name;
})
: tagGroups.map((tagGroup) => {
return tagGroup.name;
});

dirNames.forEach((directory) => {
if (!fs.existsSync(`${outputDir}/${directory}`)) {
try {
fs.mkdirSync(`${outputDir}/${directory}`, { recursive: true });
console.log(
chalk.green(`Successfully created "${outputDir}/${directory}"`)
);
} catch (err) {
console.error(
chalk.red(`Failed to create "${outputDir}/${directory}"`),
chalk.yellow(err)
);
}
}
});
}
// TODO: figure out better way to set default
if (Object.keys(sidebarOptions ?? {}).length > 0) {
else if (Object.keys(sidebarOptions ?? {}).length > 0) {
const sidebarSlice = generateSidebarSlice(
sidebarOptions!,
options,
Expand Down Expand Up @@ -350,23 +376,32 @@ custom_edit_url: null
const tagUtils = render(tagMdTemplate, item);

if (item.type === "api") {
if (!fs.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
let path = `${outputDir}/${item.id}.tag.mdx`;
if (sidebarOptions?.nested) {
path = `${outputDir}/${item.api.tags![0]}/${item.id}.api.mdx`;

if (sidebarOptions.groupPathsBy === "tagGroup") {
//get the tagGroup of the tag
tagGroups.forEach((tagGroup) => {
if (tagGroup.tags.includes(item.api.tags![0])) {
path = `${outputDir}/${tagGroup.name}/${item.id}.api.mdx`;
}
});
}
}
if (!fs.existsSync(path)) {
try {
// kebabCase(arg) returns 0-length string when arg is undefined
if (item.id.length === 0) {
throw Error(
"Operation must have summary or operationId defined"
);
}
fs.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
console.log(
chalk.green(
`Successfully created "${outputDir}/${item.id}.api.mdx"`
)
);
fs.writeFileSync(path, view, "utf8");
console.log(chalk.green(`Successfully created "${path}"`));
} catch (err) {
console.error(
chalk.red(`Failed to write "${outputDir}/${item.id}.api.mdx"`),
chalk.red(`Failed to write "${path}"`),
chalk.yellow(err)
);
}
Expand Down Expand Up @@ -401,23 +436,27 @@ custom_edit_url: null
}
}
}

if (item.type === "tag") {
if (!fs.existsSync(`${outputDir}/${item.id}.tag.mdx`)) {
let path = `${outputDir}/${item.id}.tag.mdx`;
if (sidebarOptions?.nested) {
path = `${outputDir}/${item.tag.name!}/index.mdx`;

if (sidebarOptions.groupPathsBy === "tagGroup") {
//get the tagGroup of the tag
tagGroups.forEach((tagGroup) => {
if (tagGroup.tags.includes(item.tag.name!)) {
path = `${outputDir}/${tagGroup.name}/index.mdx`;
}
});
}
}
if (!fs.existsSync(path)) {
try {
fs.writeFileSync(
`${outputDir}/${item.id}.tag.mdx`,
tagUtils,
"utf8"
);
console.log(
chalk.green(
`Successfully created "${outputDir}/${item.id}.tag.mdx"`
)
);
fs.writeFileSync(path, tagUtils, "utf8");
console.log(chalk.green(`Successfully created "${path}"`));
} catch (err) {
console.error(
chalk.red(`Failed to write "${outputDir}/${item.id}.tag.mdx"`),
chalk.red(`Failed to write "${path}"`),
chalk.yellow(err)
);
}
Expand Down Expand Up @@ -479,15 +518,17 @@ custom_edit_url: null
async function cleanApiDocs(options: APIOptions) {
const { outputDir } = options;
const apiDir = posixPath(path.join(siteDir, outputDir));
const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
cwd: path.resolve(apiDir),
deep: 1,
});
const apiMdxFiles = await Globby(
["**/*.api.mdx", "**/*.index.mdx", "**/*.info.mdx", "**/*.tag.mdx"],
{
cwd: path.resolve(apiDir),
}
);
const sidebarFile = await Globby(["sidebar.js", "sidebar.ts"], {
cwd: path.resolve(apiDir),
deep: 1,
});
apiMdxFiles.map((mdx) =>
apiMdxFiles.forEach((mdx) =>
fs.unlink(`${apiDir}/${mdx}`, (err) => {
if (err) {
console.error(
Expand All @@ -512,7 +553,7 @@ custom_edit_url: null
}
}

sidebarFile.map((sidebar) =>
sidebarFile.forEach((sidebar) =>
fs.unlink(`${apiDir}/${sidebar}`, (err) => {
if (err) {
console.error(
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-openapi-docs/src/options.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ const sidebarOptions = Joi.object({
sidebarCollapsible: Joi.boolean(),
sidebarCollapsed: Joi.boolean(),
sidebarGenerators: sidebarGenerators,
nested: Joi.boolean(),
});

const markdownGenerators = Joi.object({
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-openapi-docs/src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ export interface SidebarOptions {
sidebarCollapsible?: boolean;
sidebarCollapsed?: boolean;
sidebarGenerators?: SidebarGenerators;
nested?: boolean;
}

export interface APIVersionOptions {
Expand Down
Loading