Skip to content

Commit 27ac52d

Browse files
delucisdelucis
authored
Merge branch 'main' into fix/astro-db-language-tags
2 parents de949f2 + 9cb0b62 commit 27ac52d

6 files changed

Lines changed: 83 additions & 32 deletions

File tree

‎.vscode/settings.json‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
{
2-
"files.readonlyInclude": {
3-
"src/content/docs/en/reference/errors/*": true,
4-
"src/content/docs/en/reference/configuration-reference.mdx": true,
5-
"src/content/docs/en/reference/error-reference.mdx": true
6-
}
2+
"files.readonlyInclude": {
3+
"src/content/docs/en/reference/errors/*": true,
4+
"src/content/docs/en/reference/configuration-reference.mdx": true,
5+
"src/content/docs/en/reference/error-reference.mdx": true
6+
},
7+
"[javascript]": {
8+
"editor.defaultFormatter": "esbenp.prettier-vscode"
9+
},
10+
"[typescript]": {
11+
"editor.defaultFormatter": "esbenp.prettier-vscode"
12+
}
713
}

‎scripts/error-docgen.mjs‎

Lines changed: 54 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import fs from 'fs';
1+
import fs from 'node:fs';
22
import jsdoc from 'jsdoc-api';
33
import fetch from 'node-fetch';
44
import ts from 'typescript';
@@ -29,20 +29,24 @@ import DontEditWarning from '~/components/DontEditWarning.astro'
2929
The following reference is a complete list of the errors you may encounter while using Astro. For additional assistance, including common pitfalls, please also see our [Troubleshooting Guide](/en/guides/troubleshooting/).
3030
`;
3131

32-
const FOOTER = ``;
32+
const FOOTER = '';
3333

3434
export async function run() {
3535
const astroErrorData = await getAstroErrorsData();
3636

3737
// TODO: Implement compiler errors
3838

39+
const alreadyDocumentedErrors = fs.readdirSync('src/content/docs/en/reference/errors');
40+
41+
const documentedErrors = [];
42+
3943
let astroResult = '';
4044
for (const comment of astroErrorData.jsdoc) {
4145
// Header
4246
if (comment.kind === 'heading') {
4347
astroResult += `\n## ${comment.name}\n\n`;
4448
if (comment.description) {
45-
astroResult += comment.description.trim() + '\n\n';
49+
astroResult += `${comment.description.trim()}\n\n`;
4650
}
4751
continue;
4852
}
@@ -61,7 +65,7 @@ export async function run() {
6165
const completeReferenceEntry = [
6266
// Errors can be deprecated, as such we add a little "deprecated" caution to errors that needs it
6367
getDeprecatedText(comment.deprecated),
64-
``,
68+
'',
6569
// Get the error message and print it in a blockquote
6670
getMessage(
6771
comment.name,
@@ -70,23 +74,23 @@ export async function run() {
7074
),
7175
// Show the error's description under a header
7276
comment.description && `## What went wrong?\n${comment.description.trim()}`,
73-
``,
77+
'',
7478
// List @see entries
7579
comment.see
7680
? `**See Also:**\n${comment.see.map((s) => `- ${s.replace('-', '')}`.trim()).join('\n')}`
7781
: undefined,
78-
`\n\n`,
82+
'\n\n',
7983
]
8084
.filter((l) => l !== undefined)
8185
.join('\n')
8286
// Replace absolute links with relative ones
8387
.replace(/https\\?:\/\/docs\.astro\.build\//g, '/');
8488

8589
const fileName = getKebabFilename(comment.name);
86-
fs.writeFileSync(
87-
`src/content/docs/en/reference/errors/${fileName}.mdx`,
88-
getErrorReferenceEntryHeader(errorTitle) + completeReferenceEntry
89-
);
90+
const filePath = `src/content/docs/en/reference/errors/${fileName}.mdx`;
91+
fs.writeFileSync(filePath, getErrorReferenceEntryHeader(errorTitle) + completeReferenceEntry);
92+
93+
documentedErrors.push(`${fileName}.mdx`);
9094

9195
// Build string for error reference list
9296
astroResult += [
@@ -96,6 +100,34 @@ export async function run() {
96100
.join('\n');
97101
}
98102

103+
// Add deprecation notice for errors that are no longer emitted
104+
const deprecatedErrors = alreadyDocumentedErrors.filter(
105+
(error) => !documentedErrors.includes(error)
106+
);
107+
108+
for (const error of deprecatedErrors) {
109+
const filePath = `src/content/docs/en/reference/errors/${error}`;
110+
const currentContent = fs.readFileSync(filePath, 'utf8');
111+
112+
// If the error got removed without a deprecation, add a deprecation notice
113+
if (!currentContent.includes(':::caution[Deprecated]')) {
114+
fs.writeFileSync(
115+
filePath,
116+
currentContent.replace(
117+
'<DontEditWarning />',
118+
[
119+
'<DontEditWarning />',
120+
'',
121+
getDeprecatedText(
122+
'This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance.'
123+
),
124+
].join('\n')
125+
),
126+
'utf8'
127+
);
128+
}
129+
}
130+
99131
fs.writeFileSync(
100132
'src/content/docs/en/reference/error-reference.mdx',
101133
HEADER + astroResult + FOOTER,
@@ -124,7 +156,7 @@ export async function run() {
124156
}
125157

126158
if (resultMessage) {
127-
return resultMessage + '\n';
159+
return `${resultMessage}\n`;
128160
}
129161

130162
return undefined;
@@ -139,7 +171,7 @@ export async function run() {
139171
}
140172

141173
return [
142-
``,
174+
'',
143175
':::caution[Deprecated]',
144176
typeof deprecateMention === 'string'
145177
? deprecateMention
@@ -160,11 +192,15 @@ async function getAstroErrorsData() {
160192
const inputBuffer = STUB || (await fetch(errorURL).then((r) => r.text()));
161193

162194
const compiledResult = ts.transpileModule(inputBuffer, {
163-
compilerOptions: { module: 'esnext', target: 'esnext', removeComments: false },
195+
compilerOptions: {
196+
module: 'esnext',
197+
target: 'esnext',
198+
removeComments: false,
199+
},
164200
}).outputText;
165201

166202
const encodedJs = encodeURIComponent(compiledResult);
167-
const dataUri = 'data:text/javascript;charset=utf-8,' + encodedJs;
203+
const dataUri = `data:text/javascript;charset=utf-8,${encodedJs}`;
168204

169205
/**
170206
* @type {{AstroErrorData: Object.<string, {code: number, message: string, hint: string, name: string}>}
@@ -176,7 +212,7 @@ async function getAstroErrorsData() {
176212
*/
177213
const jsDocComments = jsdoc
178214
.explainSync({ source: compiledResult })
179-
.filter((data) => data.tags && data.tags.some((tag) => tag.title === 'docs'));
215+
.filter((data) => data.tags?.some((tag) => tag.title === 'docs'));
180216

181217
return {
182218
errors: data,
@@ -190,15 +226,15 @@ async function getAstroErrorsData() {
190226
* @returns {string}
191227
*/
192228
function getErrorReferenceEntryHeader(errorTitle) {
193-
errorTitle = errorTitle.replaceAll('`', '');
229+
const sanitizedTitle = errorTitle.replaceAll('`', '');
194230
return `
195231
---
196232
# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs'
197233
# Do not make edits to it directly, they will be overwritten.
198234
# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
199235
# Translators, please remove this note and the <DontEditWarning/> component.
200236
201-
title: ${errorTitle}
237+
title: ${sanitizedTitle}
202238
i18nReady: true
203239
githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
204240
---
@@ -241,7 +277,7 @@ function sanitizeString(message) {
241277
return message
242278
.replaceAll(/\\`/gm, '`')
243279
.replaceAll(/`?(client:[\w]+(="\(.+\)")?)`?/g, '`$1`')
244-
.replaceAll(/([^`\\])</gm, `$1\\<`)
280+
.replaceAll(/([^`\\])</gm, '$1\\<')
245281
.replaceAll(/>([^`\\])/gm, '\\$1>')
246282
.replaceAll('\\n', '<br/>');
247283
}

‎src/content/docs/en/reference/errors/env-invalid-variable.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,11 @@ import DontEditWarning from '~/components/DontEditWarning.astro'
1313
<DontEditWarning />
1414

1515

16+
:::caution[Deprecated]
17+
This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance.
18+
:::
19+
1620
> **EnvInvalidVariable**: The following environment variable does not match the data type and/or properties defined in `experimental.env.schema`: KEY is not of type TYPE
1721
1822
## What went wrong?
1923
An environment variable does not match the data type and/or properties defined in `experimental.env.schema`.
20-
21-
22-

‎src/content/docs/en/reference/errors/invalid-rewrite404.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,11 @@ import DontEditWarning from '~/components/DontEditWarning.astro'
1313
<DontEditWarning />
1414

1515

16+
:::caution[Deprecated]
17+
This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance.
18+
:::
19+
1620
> **InvalidRewrite404**: Rewriting a 404 is only allowed inside on-demand pages.
1721
1822
## What went wrong?
1923
The user tried to rewrite a 404 page inside a static page.
20-
21-
22-

‎src/content/docs/en/reference/errors/locals-not-serializable.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@ import DontEditWarning from '~/components/DontEditWarning.astro'
1313
<DontEditWarning />
1414

1515

16+
:::caution[Deprecated]
17+
This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance.
18+
:::
19+
20+
1621
> **LocalsNotSerializable**: The information stored in `Astro.locals` for the path "`HREF`" is not serializable. Make sure you store only serializable data. (E03034)
1722
1823
## What went wrong?
@@ -30,6 +35,3 @@ export const onRequest = defineMiddleware((context, next) => {
3035
return next();
3136
});
3237
```
33-
34-
35-

‎src/content/docs/en/reference/errors/markdown-content-schema-validation-error.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@ import DontEditWarning from '~/components/DontEditWarning.astro'
1313
<DontEditWarning />
1414

1515

16+
:::caution[Deprecated]
17+
This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance.
18+
:::
19+
20+
1621
> **Example error message:**<br/>
1722
Could not parse frontmatter in **blog** → **post.md**<br/>
1823
"title" is required.<br/>

0 commit comments

Comments
 (0)