Skip to content

[docs-infra] Allows to duplicate markdown #35352

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

Draft
wants to merge 3 commits into
base: v5.x
Choose a base branch
from

Conversation

alexfauquette
Copy link
Member

@alexfauquette alexfauquette commented Dec 5, 2022

Context

In the package, @mui/x-date-pickers components are not fully independent. Props are shared between multiple components, but not all of them, which makes it difficult to build the documentation. For example, the DatePicker shares a lot of logic with DateTimePickers and with their subcomponent the DayCalendar.

To avoid having to read the entire docs to customize components, we thought about the following strategy:

  • Shared properties are deeply discussed in the smallest component using them. For example calendar customization are discussed in a page about DayCalendar
  • A brief introduction is added to each page using them.

Problem

Such an approach has a major drawback: creating duplicate content. Which can lead to outdated content.

Solution

The proposed solution is to keep one source of truth for the content we want to repeat.

For example we could add the following in different doc pages

{{"insert": "../../common/pickers/DayCalendar"}}

And define the introduction with

## Calendar customization

The Calendar can be deeply customized by ...

Here is an example of how to ...

{{"demo": ....}}

For more information, have a look at ... page

I made an experiment in the Buton page of mui/base documentation

@alexfauquette alexfauquette added proof of concept Studying and/or experimenting with a to be validated approach scope: docs-infra Specific to the docs-infra product labels Dec 5, 2022
@mui-bot
Copy link

mui-bot commented Dec 5, 2022

Messages
📖 Netlify deploy preview: https://deploy-preview-35352--material-ui.netlify.app/

No bundle size changes

Generated by 🚫 dangerJS against f9594ce

@github-actions github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Jun 20, 2023
@danilo-leal danilo-leal changed the title [docs][draft] Allows to duplicate markdown [docs-infra] Allows to duplicate markdown Oct 27, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
PR: out-of-date The pull request has merge conflicts and can't be merged proof of concept Studying and/or experimenting with a to be validated approach scope: docs-infra Specific to the docs-infra product
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants