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

chore(website): upgrade Docusaurus, format files, add shiki-twoslash #1645

Merged
merged 10 commits into from
Mar 4, 2022
Merged

chore(website): upgrade Docusaurus, format files, add shiki-twoslash #1645

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0395a19
chore(website): upgrade Docusaurus, format files
Josh-Cena Feb 17, 2022
e34a3b0
remove external link icon
Josh-Cena Feb 25, 2022
bfa3e69
upgrade Docusaurus to beta.16
Josh-Cena Feb 26, 2022
f8e052d
fix lock
Josh-Cena Feb 26, 2022
b34fa81
add shiki-twoslash, pick code highlighting themes, update
cspotcode Mar 3, 2022
6080b7e
linting
cspotcode Mar 3, 2022
cf87758
beta.17
Josh-Cena Mar 4, 2022
135ec4b
point breadcrumb home to /docs
Josh-Cena Mar 4, 2022
b4a7129
fix prettier config
cspotcode Mar 4, 2022
47dbfa4
remove twoslash tsconfig renderer due to rendering bug on dark theme,…
cspotcode Mar 4, 2022
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
4 changes: 4 additions & 0 deletions .prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
!/scripts
!/src
!/tests
!/website
website/docs
website/readme-sources
website/static
tests/main-realpath/symlink/tsconfig.json
tests/throw error.ts
tests/throw error react tsx.tsx
Expand Down
54 changes: 51 additions & 3 deletions website/docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ module.exports = {
// //isCloseable: false, // Defaults to `true`.
// },
colorMode: {
respectPrefersColorScheme: true
respectPrefersColorScheme: true,
},
navbar: {
title: 'ts-node',
Expand Down Expand Up @@ -61,6 +61,20 @@ module.exports = {
},
],
},
metadata: [
{
name: 'msapplication-TileColor',
content: '#2b5797',
},
{
name: 'msapplication-config',
content: '/ts-node/img/favicon/browserconfig.xml',
},
{
name: 'theme-color',
content: '#ffffff',
},
],
Copy link
Collaborator

Choose a reason for hiding this comment

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

This looks new, what does it do? Do we need to make these colors match something else in our config?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It's a replacement for the <Head> tags you had in index.js before.

// footer: {
// style: 'dark',
// links: [
Expand Down Expand Up @@ -124,9 +138,9 @@ module.exports = {
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
editUrl:
'https://github.com/TypeStrong/ts-node/edit/docs/website/',
editUrl: 'https://github.com/TypeStrong/ts-node/edit/docs/website/',
},
blog: false,
Copy link
Contributor Author

Choose a reason for hiding this comment

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

blog: undefined would still initialize the blog plugin, which would create some default routes like /blog/archive, even if there aren't any posts.

// blog: {
// showReadingTime: true,
// // Please change this to your repo.
Expand All @@ -139,4 +153,38 @@ module.exports = {
},
],
],
// Misleading API, probably will be refactored in Docusaurus, but this is
// simply a list of <link> tags
Copy link
Contributor Author

Choose a reason for hiding this comment

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

That's more like a note to myself. I have this comment on multiple websites I helped set up now, but I still can't think of a better API. We'll probably have an htmlTags API that allows you to inject arbitrary HTML tags, not just <link>?

stylesheets: [
{
rel: 'apple-touch-icon',
sizes: '180x180',
href: '/ts-node/img/favicon/apple-touch-icon.png',
},
{
rel: 'icon',
type: 'image/png',
sizes: '32x32',
href: '/ts-node/img/favicon/favicon-32x32.png',
},
{
rel: 'icon',
type: 'image/png',
sizes: '16x16',
href: '/ts-node/img/favicon/favicon-16x16.png',
},
{
rel: 'manifest',
href: '/ts-node/img/favicon/site.webmanifest',
},
{
rel: 'mask-icon',
href: '/ts-node/img/favicon/safari-pinned-tab.svg',
color: '#5bbad5',
},
{
rel: 'shortcut icon',
href: '/ts-node/img/favicon/favicon.ico',
},
],
Copy link
Collaborator

Choose a reason for hiding this comment

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

This looks new, what does it do?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Same as above, just a replacement for the head tags so they show up on every page.

};
6 changes: 3 additions & 3 deletions website/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@
"build-readme": "./scripts/build-readme.mjs"
},
"dependencies": {
"@docusaurus/core": "2.0.0-alpha.75",
"@docusaurus/preset-classic": "2.0.0-alpha.75",
"@docusaurus/theme-search-algolia": "^2.0.0-alpha.75",
"@docusaurus/core": "2.0.0-beta.15",
"@docusaurus/preset-classic": "2.0.0-beta.15",
"@docusaurus/theme-search-algolia": "2.0.0-beta.15",
Copy link
Collaborator

Choose a reason for hiding this comment

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

I forgot we were on an alpha version, I guess alpha->beta is an improvement in stability.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The semantic difference between alpha and beta is not super big since we still ship breaking changes. The beta bump was mostly because we finally reached feature parity with v1 after the i18n release, so we are almost there for a stable release

"@mdx-js/react": "^1.6.21",
"@types/js-yaml": "^4.0.0",
"clsx": "^1.1.1",
Expand Down
93 changes: 53 additions & 40 deletions website/scripts/build-readme.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ const readmePath = Path.resolve(__root, 'README.md');
const generateReadmeHeadersForCategories = {
General: false,
Advanced: true,
Recipes: true
Recipes: true,
};

import sidebars from '../sidebars.js';
Expand All @@ -35,42 +35,50 @@ async function main() {

await appendMarkdownFileToReadmeAst({
path: 'readme-sources/prefix.md',
headerLevel: 1
headerLevel: 1,
});

const sidebar = sidebars.primarySidebar;
for(const category of sidebar) {
const generateReadmeHeader = generateReadmeHeadersForCategories[category.label];
if(generateReadmeHeader) {
for (const category of sidebar) {
const generateReadmeHeader =
generateReadmeHeadersForCategories[category.label];
if (generateReadmeHeader) {
readmeNodes.push(headerNode(1, category.label));
} else if(generateReadmeHeader == null) {
throw new Error(`Update ${ import.meta.url } to include all sidebar categories`);
} else if (generateReadmeHeader == null) {
throw new Error(
`Update ${import.meta.url} to include all sidebar categories`
);
}
for(const page of category.items) {
for (const page of category.items) {
await appendMarkdownFileToReadmeAst({
path: `docs/${ page }.md`,
headerLevel: 1 + !!generateReadmeHeader
path: `docs/${page}.md`,
headerLevel: 1 + !!generateReadmeHeader,
});
}
}

appendMarkdownFileToReadmeAst({
path: 'readme-sources/license.md',
headerLevel: 1
headerLevel: 1,
});

async function appendMarkdownFileToReadmeAst({path, headerLevel}) {
async function appendMarkdownFileToReadmeAst({ path, headerLevel }) {
const absPath = Path.resolve(__websiteRoot, path);
console.log(`Appending ${ path } at header level ${ headerLevel }`);
console.log(`Appending ${path} at header level ${headerLevel}`);
const markdownSource = fs.readFileSync(absPath, 'utf8');
await remark()
.use(remarkFrontmatter, ['yaml'])
.use(parseFrontmatter)
.use(remarkBehead, { after: '', depth: headerLevel - 1 })
.use(() => (ast) => {
const {frontmatter} = ast;
if(frontmatter && !frontmatter.omitHeaderOnMerge) {
readmeNodes.push(headerNode(headerLevel, frontmatter && frontmatter.title || Path.basename(absPath)));
const { frontmatter } = ast;
if (frontmatter && !frontmatter.omitHeaderOnMerge) {
readmeNodes.push(
headerNode(
headerLevel,
(frontmatter && frontmatter.title) || Path.basename(absPath)
)
);
}
readmeNodes.push(...ast.children);
})
Expand All @@ -84,73 +92,78 @@ async function main() {
.use(codeLanguageJsonToJsonc)
.use(rewritePageLinksToAnchorLinks)
.use(rewriteImgTargets)
.use(remarkToc, {tight: true})
.process(vfile({
path: readmePath,
contents: ''
}));
.use(remarkToc, { tight: true })
.process(
vfile({
path: readmePath,
contents: '',
})
);
console.error(vfileReporter(renderedReadme));
if(renderedReadme.messages.length) throw new Error('Aborting on diagnostics.');
if (renderedReadme.messages.length)
throw new Error('Aborting on diagnostics.');
const lintResults = await remark()
.use(remarkValidateLinks)
.use(remarkRecommended)
.process(renderedReadme);
console.error(vfileReporter(lintResults));
if(lintResults.messages.length) throw new Error('Aborting on diagnostics.');
if (lintResults.messages.length) throw new Error('Aborting on diagnostics.');

fs.writeFileSync(readmePath, renderedReadme.contents);
}

function parseFrontmatter() {
return (ast) => {
if(ast.children[0].type === 'yaml') {
if (ast.children[0].type === 'yaml') {
ast.frontmatter = jsYaml.load(ast.children[0].value);
ast.children.splice(0, 1);
}
}
};
}

function codeLanguageJsonToJsonc() {
return (ast) => {
visit(ast, 'code', node => {
if(node.lang === 'json') node.lang = 'jsonc';
})
}
visit(ast, 'code', (node) => {
if (node.lang === 'json') node.lang = 'jsonc';
});
};
}
function rewritePageLinksToAnchorLinks() {
return (ast) => {
visit(ast, 'link', node => {
if(node.url?.match?.(/^https?\:\/\//)) return;
visit(ast, 'link', (node) => {
if (node.url?.match?.(/^https?\:\/\//)) return;
// TODO take page title into account
node.url = node.url.replace(/^[\.\/]*(?:([^#]+)|.*#(.*))$/, '#$1$2');
node.url = node.url.replace(/\.md$/, '');
});
}
};
}

function rewriteImgTargets() {
return (ast) => {
visit(ast, 'image', node => {
visit(ast, 'image', (node) => {
node.url = node.url.replace(/^\//, 'website/static/');
});
}
};
}

function headerNode(depth, value) {
return {
type: 'heading',
depth,
children: [{
type: 'text',
value,
children: []
}]
children: [
{
type: 'text',
value,
children: [],
},
],
};
}

try {
await main();
} catch(e) {
} catch (e) {
console.error(e.message);
process.exitCode = 1;
}
102 changes: 53 additions & 49 deletions website/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,51 +1,55 @@
module.exports = {
primarySidebar: [{
type: 'category',
label: 'General',
collapsed: false,
items: [
'overview',
'installation',
'usage',
'configuration',
'options',
'imports',
'troubleshooting',
'performance',
]
}, {
type: 'category',
label: 'Advanced',
collapsed: false,
items: [
'how-it-works',
'paths',
'types',
'compilers',
'transpilers',
'module-type-overrides'
],
}, {
type: 'category',
label: 'Recipes',
collapsed: false,
items: [
'recipes/watching-and-restarting',
'recipes/ava',
'recipes/gulp',
'recipes/intellij',
'recipes/mocha',
'recipes/tape',
'recipes/visual-studio-code',
'recipes/other'
]
}],
hiddenSidebar: [{
type: 'category',
label: 'Hidden pages',
collapsed: false,
items: [
'options-table',
]
}],
primarySidebar: [
{
type: 'category',
label: 'General',
collapsed: false,
items: [
'overview',
'installation',
'usage',
'configuration',
'options',
'imports',
'troubleshooting',
'performance',
],
},
{
type: 'category',
label: 'Advanced',
collapsed: false,
items: [
'how-it-works',
'paths',
'types',
'compilers',
'transpilers',
'module-type-overrides',
],
},
{
type: 'category',
label: 'Recipes',
collapsed: false,
items: [
'recipes/watching-and-restarting',
'recipes/ava',
'recipes/gulp',
'recipes/intellij',
'recipes/mocha',
'recipes/tape',
'recipes/visual-studio-code',
'recipes/other',
],
},
],
hiddenSidebar: [
{
type: 'category',
label: 'Hidden pages',
collapsed: false,
items: ['options-table'],
},
],
};
Loading