[Next Docs] Update Git Workflow (#50579)
Update our git workflow in preparation for open-sourcing the content of the docs ([linear task](https://linear.app/vercel/issue/DX-1579/set-up-github-workflow)). **Templates:** - [x] Update docs issue template to encourage contributions - [x] Update PR template to include link to new contribution guide **Code Owners / Reviewers:** - https://github.com/vercel/next.js/pull/50841 **Labels:** - [x] Add DevEx team to labeler.json so PRs get the "created by: DevEx team" **Other:** - [x] Remove docs manifest from CI checks as we no longer have one (keep the manifest for errors as they live under `/pages`) - [x] Add `unifiedjs.vscode-mdx` to the vscode extension list
This commit is contained in:
parent
22ea7d9909
commit
f6ff2ef98e
6 changed files with 52 additions and 73 deletions
6
.github/ISSUE_TEMPLATE/4.docs_request.yml
vendored
6
.github/ISSUE_TEMPLATE/4.docs_request.yml
vendored
|
@ -4,6 +4,12 @@ title: 'Docs: '
|
|||
labels:
|
||||
- 'template: documentation'
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: Before opening this issue to request a docs improvement, is this something you can help us with? Your contributions are welcomed and appreciated. See our [Docs Contribution Guide](https://nextjs.org/docs/community/contribution-guide) to learn how to edit the Next.js docs.
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: Thank you for helping us improve the docs!
|
||||
- type: textarea
|
||||
attributes:
|
||||
label: What is the improvement or update you wish to see?
|
||||
|
|
15
.github/labeler.json
vendored
15
.github/labeler.json
vendored
|
@ -26,7 +26,6 @@
|
|||
{ "type": "user", "pattern": "JanKaifer" },
|
||||
{ "type": "user", "pattern": "javivelasco" },
|
||||
{ "type": "user", "pattern": "kikobeats" },
|
||||
{ "type": "user", "pattern": "leerob" },
|
||||
{ "type": "user", "pattern": "schniz" },
|
||||
{ "type": "user", "pattern": "sebmarkbage" },
|
||||
{ "type": "user", "pattern": "shuding" },
|
||||
|
@ -34,10 +33,18 @@
|
|||
{ "type": "user", "pattern": "timneutkens" },
|
||||
{ "type": "user", "pattern": "wyattjoh" }
|
||||
],
|
||||
"created-by: Next.js docs team": [
|
||||
"created-by: Next.js DevEx team": [
|
||||
{ "type": "user", "pattern": "leerob" },
|
||||
{ "type": "user", "pattern": "ismaelrumzan" },
|
||||
{ "type": "user", "pattern": "MaedahBatool" },
|
||||
{ "type": "user", "pattern": "molebox" }
|
||||
{ "type": "user", "pattern": "molebox" },
|
||||
{ "type": "user", "pattern": "delbaoliveira" },
|
||||
{ "type": "user", "pattern": "lydiahallie" },
|
||||
{ "type": "user", "pattern": "steven-tey" },
|
||||
{ "type": "user", "pattern": "nutlope" },
|
||||
{ "type": "user", "pattern": "stephdietz" },
|
||||
{ "type": "user", "pattern": "timeyoutakeit" },
|
||||
{ "type": "user", "pattern": "s3prototype" },
|
||||
{ "type": "user", "pattern": "manovotny" }
|
||||
],
|
||||
"created-by: web-tooling team": [
|
||||
{ "type": "user", "pattern": "alexkirsz" },
|
||||
|
|
6
.github/pull_request_template.md
vendored
6
.github/pull_request_template.md
vendored
|
@ -4,7 +4,11 @@ Choose the right checklist for the change(s) that you're making:
|
|||
|
||||
## For Contributors
|
||||
|
||||
### Improving Documentation or adding/fixing Examples
|
||||
### Improving Documentation
|
||||
|
||||
- Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide
|
||||
|
||||
### Adding or Updating Examples
|
||||
|
||||
- The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
|
||||
- Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
|
||||
|
|
5
.vscode/extensions.json
vendored
5
.vscode/extensions.json
vendored
|
@ -19,6 +19,9 @@
|
|||
"ms-vsliveshare.vsliveshare",
|
||||
|
||||
// Debugging
|
||||
"ms-vscode.vscode-js-profile-flame"
|
||||
"ms-vscode.vscode-js-profile-flame",
|
||||
|
||||
// MDX Authoring
|
||||
"unifiedjs.vscode-mdx"
|
||||
]
|
||||
}
|
||||
|
|
|
@ -1,40 +1,3 @@
|
|||
# Updating Documentation Paths
|
||||
# Contributing to Documentation
|
||||
|
||||
Our documentation currently leverages a [manifest file](/docs/manifest.json), which is how documentation entries are checked.
|
||||
|
||||
When adding a new entry under an existing category you only need to add an entry with `{title: '', path: '/docs/path/to/file.md'}`. The "title" is what is shown on the sidebar.
|
||||
|
||||
When moving the location/url of an entry, the "title" field can be removed from the existing entry and the ".md" extension removed from the "path", then a "redirect" field with the shape of `{permanent: true/false, destination: '/some-url'}` can be added. A new entry should be added with the "title" and "path" fields if the document is renamed within the [`docs` folder](/docs) that points to the new location in the folder, e.g. `/docs/some-url.md`
|
||||
|
||||
Example of moving documentation file:
|
||||
|
||||
Before:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"path": "/docs/original.md",
|
||||
"title": "Hello world"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"path": "/docs/original",
|
||||
"redirect": {
|
||||
"permanent": false,
|
||||
"destination": "/new"
|
||||
}
|
||||
},
|
||||
{
|
||||
"path": "/docs/new.md",
|
||||
"title": "Hello world"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
> **Note**: The manifest is checked automatically in the "lint" step in CI when opening a PR.
|
||||
See the [Docs Contribution Guide](https://nextjs.org/docs/community/contribution-guide) to learn how to contribute to the Next.js Documentation.
|
||||
|
|
|
@ -19,41 +19,37 @@ function collectPaths(routes, paths = []) {
|
|||
}
|
||||
|
||||
async function main() {
|
||||
const manifests = ['errors/manifest.json', 'docs/manifest.json']
|
||||
const manifest = 'errors/manifest.json'
|
||||
let hadError = false
|
||||
|
||||
for (const manifest of manifests) {
|
||||
const dir = path.dirname(manifest)
|
||||
const files = await glob(path.join(dir, '**/*.md'))
|
||||
const dir = path.dirname(manifest)
|
||||
const files = await glob(path.join(dir, '**/*.md'))
|
||||
|
||||
const manifestData = JSON.parse(
|
||||
await fs.promises.readFile(manifest, 'utf8')
|
||||
)
|
||||
const manifestData = JSON.parse(await fs.promises.readFile(manifest, 'utf8'))
|
||||
|
||||
const paths = []
|
||||
collectPaths(manifestData.routes, paths)
|
||||
const paths = []
|
||||
collectPaths(manifestData.routes, paths)
|
||||
|
||||
const missingFiles = files.filter(
|
||||
(file) => !paths.includes(`/${file}`) && file !== 'errors/template.md'
|
||||
)
|
||||
const missingFiles = files.filter(
|
||||
(file) => !paths.includes(`/${file}`) && file !== 'errors/template.md'
|
||||
)
|
||||
|
||||
if (missingFiles.length) {
|
||||
if (missingFiles.length) {
|
||||
hadError = true
|
||||
console.log(`Missing paths in ${manifest}:\n${missingFiles.join('\n')}`)
|
||||
} else {
|
||||
console.log(`No missing paths in ${manifest}`)
|
||||
}
|
||||
|
||||
for (const filePath of paths) {
|
||||
if (
|
||||
!(await fs.promises
|
||||
.access(path.join(process.cwd(), filePath), fs.constants.F_OK)
|
||||
.then(() => true)
|
||||
.catch(() => false))
|
||||
) {
|
||||
console.log('Could not find path:', filePath)
|
||||
hadError = true
|
||||
console.log(`Missing paths in ${manifest}:\n${missingFiles.join('\n')}`)
|
||||
} else {
|
||||
console.log(`No missing paths in ${manifest}`)
|
||||
}
|
||||
|
||||
for (const filePath of paths) {
|
||||
if (
|
||||
!(await fs.promises
|
||||
.access(path.join(process.cwd(), filePath), fs.constants.F_OK)
|
||||
.then(() => true)
|
||||
.catch(() => false))
|
||||
) {
|
||||
console.log('Could not find path:', filePath)
|
||||
hadError = true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
Loading…
Reference in a new issue