docs: add note about files being ignored when prefixed with an unders…

[KyrietS]

Documentation does not mention the fact that all files prefixed with an underscores are ignored. I had some markdown pages prefixed this way and after Docusaurus upgrade they disappeared.

Motivation

Documentation doesn't mention this important fact.

Have you read the Contributing Guidelines on pull requests?

👍

Test Plan

n/a

Related PRs

n/a

[facebook-github-bot]

Hi @KyrietS!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

[netlify]

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: 0046932

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/613a5c4e7cfb6400072d8b4a

😎 Browse the preview: https://deploy-preview-5543--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	96
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5543--docusaurus-2.netlify.app/

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[lex111]

Thanks, but this feature is documented in separate section.
https://docusaurus.io/docs/markdown-features/react#importing-markdown
Did you read it?

[KyrietS]

Hi @lex111,
No, I didn't find it 😅. When I realized that _myPage.md is not generating then I searched the docs for the phrase "underscore". I never would have guessed that this information would be in the section about importing Markdown files in React...

I still think this information should be a little more exposed. But if you disagree then I don't mind closing this PR.

[lex111]

Since this is stand-alone functionality that should better be documented in single place. Let's just add an explanatory keyword "underscore" after _ to improve the search results.

By convention, using the _ (underscore) filename prefix ...

[Josh-Cena]

I agree with @KyrietS. If I'm a normal user who never uses JSX syntax in Markdown, I shouldn't be obligated to read that section (even when it's technically in the "Guides" section—people are lazy and only read those they need). I read the "Create a doc" and it tells me to create a Markdown file, but when I did, nothing shows up.

For these casual users, it's better to explain everything they need in one place instead of having the essential information scattered everywhere. (For example, we just recently added duplicated explanations about the relationship between preset config and plugin config everywhere—it's certainly not undocumented before, but more clarification is never harmful)

[lex111]

Alright, I don't mind that, but let's also add link to corresponding section describing this functionality.

[KyrietS]

Alright, I've added a link:

All files prefixed with an underscore (_) under the docs directory are treated as "partial" pages and will be ignored by default.

Read more about importing partial pages.

[lex111]

@KyrietS thanks!