Chore: (Docs) Auto docs fixes #21122
Conversation
Co-authored-by: Jeppe Reinhold <jeppe@chromatic.com>
Co-authored-by: Jeppe Reinhold <jeppe@chromatic.com>
docs/snippets/common/storybook-auto-docs-baseline-example.custom-title.mdx.mdx
Show resolved
Hide resolved
docs/snippets/common/storybook-auto-docs-baseline-example.custom-title.mdx.mdx
Outdated
Show resolved
Hide resolved
docs/snippets/common/storybook-main-fix-imports-autodocs-monorepo.js.mdx
Show resolved
Hide resolved
/cc @JReinhold |
There was a problem hiding this comment.
Nice work, overall! 👏
I'm marking this as 'Request changes' due to the coreFrameworks change, which must be resolved prior to merging.
| | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `disable` | Toggles support for all documentation pages <br/> `docs: { disable:true }` | | ||
| | `autodocs` | Configures auto-generated documentation pages. Available options: `true`, `false`,`tags` (default) <br/> `docs: { autodocs: false }` | | ||
| | `defaultName` | Renames the auto-generated documentation page<br/> `docs: { defaultName: 'Documentation' }` | | ||
|
|
||
| ### Write a custom template |
There was a problem hiding this comment.
I'm not quite sure how to think about this in combination with @kylegach's PR, but I think writing a custom autodocs template is very advanced and should at the least come at the end, if not in a totally separate page from the basic autodocs documentation.
Also we should talk in the basic docs about how to use parameters to control autodocs.
| ### Linking to other stories and pages | ||
|
|
||
| Another way to improve documentation is by linking to other stories and pages. Suppose you already have a component story with the following unique identifier, `some--id`, and you want to link it to your documentation page. In that case, you can use the `path` query string to redirect to the documentation entry related to the story: | ||
|
|
||
| ```md | ||
| [Go to specific documentation page](?path=/docs/some--id) |
There was a problem hiding this comment.
If we think this is important enough to document should we have a pattern for it that doesn't involve using (brittle) ids but instead uses the of={} syntax @shilman @JReinhold?
There was a problem hiding this comment.
Hmm I don't know, but I can imagine linking between docs pages or to stories is a common pattern. What you're suggesting sounds like a new <Link to={ButtonStories} /> block, which seems valuable to me.
Something to explore in upcoming releases for sure.
There was a problem hiding this comment.
OK, I guess we leave this for now, but I wonder if we should adding documentation that we probably plan to deprecate soon 🤷
There was a problem hiding this comment.
This was left in on a temporary basis until there's an API to address this to avoid the issues related to linking that continue to surface in the repo addressed. Once we have a stable API and a path moving forward, this section will be rewritten.
|
|
||
| Considering a story with ID `some--id`, this redirects to the **Docs** tab of the story: | ||
| By default, running the [migration command](#automigration) will try and migrate all existing MDX files in your project according to the MDX 2 specification. However, this might not always be possible, and you might run into issues during the migration. To help you troubleshoot those issues, we've prepared some recommendations that might help you. |
There was a problem hiding this comment.
PS should this content be in our migration guide rather than the docs themselves? It doesn't see relevant to new users.
There was a problem hiding this comment.
I disagree. We should instead leave it here instead of the public notion doc acting as a migration guide, as this will affect not only new users but also existing users. As most folks will not see it, by adding it, we have the added bonus of discoverability via searching the documentation. Also, to which the CLI should also point here.
With this pull request, the documentation was updated to clarify and fix some breaking changes regarding the restructuring of various sections.
What was done:
docsOptions.disable#20913, MDX2: Add automigration for GFM support #20091, [Bug]: [7.0.0 beta]autodocsdoes not generate description for components imported from local workspace package #21007