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

feat(v2): add support to ignore files in pages plugin #3196

Merged
merged 18 commits into from
Aug 5, 2020
Merged

feat(v2): add support to ignore files in pages plugin #3196

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
b329400
add support to ignore pages
Aug 3, 2020
4457a2e
fix import problem
Aug 3, 2020
284a5cf
Update website/docs/guides/creating-pages.md
Aug 3, 2020
9ea4b05
Revert "fix import problem"
Aug 3, 2020
b1756c0
Merge branch 'master' of github.com:facebook/docusaurus into anshul/page
Aug 3, 2020
42ec489
Merge branch 'anshul/page' of github.com:MLH-Fellowship/docusaurus in…
Aug 3, 2020
be85fb8
revert
Aug 3, 2020
3ca0717
fix slash
Aug 3, 2020
4a74d24
forbid frontmatter
Aug 4, 2020
1951813
fix formatting
Aug 4, 2020
ce2a313
Merge branch 'master' into anshul/page
slorber Aug 5, 2020
aafb429
Update website/docs/guides/creating-pages.md
slorber Aug 5, 2020
728448b
Update website/src/pages/examples/_chapter1.md
slorber Aug 5, 2020
6303924
Update website/src/pages/examples/_chapter2.mdx
slorber Aug 5, 2020
eb74fb5
Update website/src/pages/examples/markdownPageExample.md
slorber Aug 5, 2020
0208e61
Update website/src/pages/examples/markdownPageExample.md
slorber Aug 5, 2020
b35cee7
Update website/src/pages/examples/markdownPageExample.md
slorber Aug 5, 2020
c36e84d
Update website/src/pages/examples/markdownPageExample.md
slorber Aug 5, 2020
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
10 changes: 6 additions & 4 deletions packages/docusaurus-mdx-loader/src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
*/

const {getOptions} = require('loader-utils');
const {readFile} = require('fs-extra');
const {readFile, existsSync} = require('fs-extra');
const mdx = require('@mdx-js/mdx');
const emoji = require('remark-emoji');
const matter = require('gray-matter');
Expand Down Expand Up @@ -60,9 +60,11 @@ module.exports = async function (fileString) {
if (metadataPath) {
// Add as dependency of this loader result so that we can
// recompile if metadata is changed.
this.addDependency(metadataPath);
const metadata = await readFile(metadataPath, 'utf8');
exportStr += `\nexport const metadata = ${metadata};`;
if (existsSync(metadataPath)) {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prefer async variant whenever it's not too annoying to apply like here

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not totally sure of what this code do but I think we should not modify the loader there, as it's less fail-fast, and could silently ignore some important errors (like not having the createData and mdx loader paths in sync, not sure)

Instead we could modify the loader usage in pages like:

                    metadataPath: (mdxPath: string) => {
                      if (isIgnored(mdxPath)) { 
                        return undefined;
                      }
                      const aliasedSource = aliasedSitePath(mdxPath, siteDir);
                      return path.join(
                        dataDir,
                        `${docuHash(aliasedSource)}.json`,
                      );
                    },

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did same earlier but then I tried importing file in docs and blogs plugins and failed in both.

That looks good but a few things to change.

Wonder what's the behavior if I put frontmatter in a _file.md, maybe we should throw an exception explaining this is forbidden to the user. Also worth to add a test for that

Frontmatter is not in plugin control. It will require changes to mdx-loader

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will take a look on next review.

I think we could have a mdx loader option like forbidFrontmatter: (mdxPath: string) => boolean

this.addDependency(metadataPath);
const metadata = await readFile(metadataPath, 'utf8');
exportStr += `\nexport const metadata = ${metadata};`;
}
}
}

Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-pages/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
"@hapi/joi": "17.1.1",
"globby": "^10.0.1",
"loader-utils": "^1.2.3",
"minimatch": "^3.0.4",
slorber marked this conversation as resolved.
Show resolved Hide resolved
"remark-admonitions": "^1.2.1"
},
"peerDependencies": {
Expand Down
1 change: 1 addition & 0 deletions ...saurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/_ignore.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export default (a,b)=>a+b
1 change: 1 addition & 0 deletions ...gin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/_ignore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# ignored
1 change: 1 addition & 0 deletions ...in-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/_ignore.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# ignored
1 change: 1 addition & 0 deletions ...aurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/_ignore.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export default (a:number,b:number)=>a+b;
3 changes: 2 additions & 1 deletion packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import {PluginOptions} from '../types';

export default function normalizePluginOptions(
options: Partial<PluginOptions>,
) {
): PluginOptions {
const {value, error} = PluginOptionSchema.validate(options, {
convert: false,
});
Expand All @@ -37,6 +37,7 @@ describe('normalizePagesPluginOptions', () => {
path: 'src/my-pages',
routeBasePath: 'my-pages',
include: ['**/*.{js,jsx,ts,tsx}'],
exclude: ['**/$*/'],
};
const value = normalizePluginOptions(userOptions);
expect(value).toEqual({...DEFAULT_OPTIONS, ...userOptions});
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-pages/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ export default function pluginContentPages(
const {baseUrl} = siteConfig;
const pagesFiles = await globby(include, {
cwd: pagesDir,
ignore: options.exclude,
});

function toMetadata(relativeSource: string): Metadata {
Expand Down
2 changes: 2 additions & 0 deletions packages/docusaurus-plugin-content-pages/src/pluginOptionSchema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,14 @@ export const DEFAULT_OPTIONS: PluginOptions = {
remarkPlugins: [],
rehypePlugins: [],
admonitions: {},
exclude: ['**/_*.{js,jsx,ts,tsx,md,mdx}'],
anshulrgoyal marked this conversation as resolved.
Show resolved Hide resolved
};

export const PluginOptionSchema = Joi.object({
path: Joi.string().default(DEFAULT_OPTIONS.path),
routeBasePath: Joi.string().default(DEFAULT_OPTIONS.routeBasePath),
include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
mdxPageComponent: Joi.string().default(DEFAULT_OPTIONS.mdxPageComponent),
remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-pages/src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ export interface PluginOptions {
path: string;
routeBasePath: string;
include: string[];
exclude: string[];
mdxPageComponent: string;
remarkPlugins: ([Function, object] | Function)[];
rehypePlugins: string[];
Expand Down
5 changes: 3 additions & 2 deletions website/docs/guides/creating-pages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,14 +91,15 @@ In this component-based development era, it is encouraged to co-locate your styl
- Add a `/src/pages/support.js` file
- Create a `/src/pages/support/` directory and a `/src/pages/support/index.js` file.

The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`).
The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (`styles.module.css`) with styles meant to only be used on the "Support" page. **Note:** this is merely a recommended directory structure and you will still need to manually import the CSS module file within your component module (`support/index.js`). Any Markdown or Javascript file starting with `_` will be ignored and no routes will be created for that file.
slorber marked this conversation as resolved.
Show resolved Hide resolved

```sh
my-website
├── src
│ └── pages
│ ├── styles.module.css
│ ├── index.js
| ├──_ignored.js
│ └── support
│ ├── index.js
│ └── styles.module.css
Expand All @@ -107,7 +108,7 @@ my-website

:::caution

All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. Do not put reusable components or test files (ending with `.test.js`) into that directory otherwise they will be turned into pages, which might not be intended.
All JavaScript/TypeScript files within the `src/pages/` directory except file starting with `_` will have corresponding website paths generated for them. Do not put reusable components or test files (ending with `.test.js`) into that directory otherwise they will be turned into pages, which might not be intended.
anshulrgoyal marked this conversation as resolved.
Show resolved Hide resolved

:::

Expand Down
6 changes: 5 additions & 1 deletion website/docs/using-plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,11 @@ module.exports = {
* do not include trailing slash
*/
routeBasePath: '',
include: ['**/*.{js,jsx}'],
include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
/**
* No Route will be created for matching files
*/
exclude: ['**/_*.{js,jsx,ts,tsx,md,mdx}'],
/**
* Theme component used by markdown pages.
*/
Expand Down
1 change: 1 addition & 0 deletions website/src/pages/examples/_ignore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
This file is ignored and no route is created but it can be imported
1 change: 1 addition & 0 deletions website/src/pages/examples/_ignore_mdx.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# other file
18 changes: 18 additions & 0 deletions website/src/pages/examples/markdownPageExample.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: Markdown Page example title
description: Markdown Page example description
---

import Comp from "./\_ignore.md"

# Markdown page

This is a page generated from markdown to illustrate the markdown page feature.
Expand Down Expand Up @@ -32,3 +34,19 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs defaultValue="apple" values={[ {label: 'Apple', value: 'apple'}, {label: 'Orange', value: 'orange'}, {label: 'Banana', value: 'banana'} ]}><TabItem value="apple">This is an apple 🍎</TabItem><TabItem value="orange">This is an orange 🍊</TabItem><TabItem value="banana">This is a banana 🍌</TabItem></Tabs>

## Import Mdx and Md files

```js
// *.md file
import Comp from './_ignore.md';

// *.mdx file
import OtherComp from './_ignore_mdx.mdx';
```
slorber marked this conversation as resolved.
Show resolved Hide resolved

import OtherComp from './\_ignore_mdx.mdx'; <Comp />

<Comp/>

<OtherComp/>
52 changes: 0 additions & 52 deletions yarn.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8346,58 +8346,6 @@ doctrine@^3.0.0:
dependencies:
esutils "^2.0.2"

docusaurus@^2.0.0-alpha.61:
anshulrgoyal marked this conversation as resolved.
Show resolved Hide resolved
version "2.0.0-alpha.61"
resolved "https://registry.yarnpkg.com/docusaurus/-/docusaurus-2.0.0-alpha.61.tgz#f347b81c98c66f1de3ecfccf63fa421ddff52fbb"
integrity sha512-qDU3nOA4Xs95tIjjSETnEuRmTukTzgxyTZ5MgMyuG7y6h4oDHtpLcYf8F+xlXuuWHKv3VSxRJNzV8fZHPgnK3g==
dependencies:
"@babel/core" "^7.9.0"
"@babel/plugin-proposal-class-properties" "^7.8.3"
"@babel/plugin-proposal-object-rest-spread" "^7.9.0"
"@babel/polyfill" "^7.8.7"
"@babel/preset-env" "^7.9.0"
"@babel/preset-react" "^7.9.4"
"@babel/register" "^7.9.0"
"@babel/traverse" "^7.9.0"
"@babel/types" "^7.9.0"
autoprefixer "^9.7.5"
babylon "^6.18.0"
chalk "^3.0.0"
classnames "^2.2.6"
commander "^4.0.1"
crowdin-cli "^0.3.0"
cssnano "^4.1.10"
escape-string-regexp "^2.0.0"
express "^4.17.1"
feed "^4.0.0"
fs-extra "^8.1.0"
gaze "^1.1.3"
github-slugger "^1.2.1"
glob "^7.1.6"
highlight.js "^9.16.2"
imagemin "^6.0.0"
imagemin-gifsicle "^6.0.1"
imagemin-jpegtran "^6.0.0"
imagemin-optipng "^6.0.0"
imagemin-svgo "^7.0.0"
lodash "^4.17.15"
markdown-toc "^1.2.0"
mkdirp "^0.5.1"
portfinder "^1.0.25"
postcss "^7.0.23"
prismjs "^1.17.1"
react "^16.8.4"
react-dev-utils "^9.1.0"
react-dom "^16.8.4"
remarkable "^2.0.0"
request "^2.88.0"
shelljs "^0.8.4"
sitemap "^3.2.2"
tcp-port-used "^1.0.1"
tiny-lr "^1.1.1"
tree-node-cli "^1.2.5"
truncate-html "^1.0.3"

dom-converter@^0.2:
version "0.2.0"
resolved "https://registry.yarnpkg.com/dom-converter/-/dom-converter-0.2.0.tgz#6721a9daee2e293682955b6afe416771627bb768"
Expand Down