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.

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

Adapt DocCardList for the Teleport docs site #86

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

ptgott
Copy link
Contributor

@ptgott ptgott commented Dec 27, 2024

Partially addresses #29

Swizzle the Docusaurus-native DocCardList component and adapt it to suit the Teleport docs site. Since we prefer a more text-oriented approach to components, edit DocCardList to return a plain ul, rather than tiles.

Since the DocCardList component is a Docusaurus-native alternative to our remark-toc plugin, edit remark-toc to return a DocCardList instead of querying the filesystem to generate a table of contents. Once we replace all (!toc!) expressions with <DocCardList /> elements, we can remove remark-toc entirely.

Also make DocCardList an MDX component so docs authors don't need to add import statements to the top of a docs page.

Copy link

github-actions bot commented Dec 27, 2024

Amplify deployment status

Branch Commit Job ID Status Preview Updated (UTC)
paul.gottschling/29-toc 3960825 7 ❌FAILED paul-gottschling-29-toc 2025-01-03 21:09:56

src/theme/DocCardList/index.tsx Fixed Show resolved Hide resolved
Partially addresses #29

Swizzle the Docusaurus-native `DocCardList` component and adapt it to
suit the Teleport docs site. Since we prefer a more text-oriented
approach to components, edit `DocCardList` to return a plain `ul`,
rather than tiles.

Since the `DocCardList` component is a Docusaurus-native alternative to
our `remark-toc` plugin, edit `remark-toc` to return a `DocCardList`
instead of querying the filesystem to generate a table of contents. Once
we replace all `(!toc!)` expressions with `<DocCardList />` elements, we
can remove `remark-toc` entirely.

Also make `DocCardList` an MDX component so docs authors don't need to
add `import` statements to the top of a docs page.
@ptgott ptgott force-pushed the paul.gottschling/29-toc branch from 6745cb4 to 3960825 Compare January 3, 2025 20:59
@ptgott ptgott requested review from avatus and mmcallister January 3, 2025 21:01
@ptgott
Copy link
Contributor Author

ptgott commented Jan 6, 2025

Getting a bunch of errors like this in the Amplify preview build:

                                    Error: Can't render static file for pathname "/docs/ver/15.x/admin-guides/"
                                    at generateStaticFile (/codebuild/output/src1318284211/src/docs-website/node_modules/@docusaurus/core/lib/ssg/ssg.js:167:15)
                                    at processTicksAndRejections (node:internal/process/task_queues:105:5)
                                    at runNextTicks (node:internal/process/task_queues:69:3)
                                    at process.processImmediate (node:internal/timers:479:9)
                                    at async /codebuild/output/src1318284211/src/docs-website/node_modules/p-map/index.js:57:22 {
                                    [cause]: Error: no version doc found by id=/docs/ver/15.x/admin-guides/access-controls/access-controls
                                    at useDocById (server.bundle.js:34545:15)
                                    at /codebuild/output/src1318284211/src/docs-website/build/docs/__server/assets/js/17896441.a234c906.js:4881:61
                                    at Array.map (<anonymous>)
                                    at DocCardList (/codebuild/output/src1318284211/src/docs-website/build/docs/__server/assets/js/17896441.a234c906.js:4869:77)
                                    at Uc (server.bundle.js:3352:44)
                                    at Xc (server.bundle.js:3354:253)
                                    at Z (server.bundle.js:3360:89)
                                    at Xc (server.bundle.js:3354:481)
                                    at Z (server.bundle.js:3360:89)
                                    at Xc (server.bundle.js:3354:481)
                                    },

I'm guessing this is because the preview site doesn't include /docs/ in page paths, but I'll need to look into this more!

@ptgott ptgott marked this pull request as draft January 6, 2025 14:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants