From ed0f26cf82b1ecdb783ca44ae17b3990baf3e8cd Mon Sep 17 00:00:00 2001 From: Paul Schultz Date: Fri, 10 Mar 2023 10:45:50 -0600 Subject: [PATCH 1/3] Update prism style to vsDark Signed-off-by: Paul Schultz --- .../software-templates/testing-scaffolder-alpha.md | 4 ++-- microsite/docusaurus.config.js | 8 +++++++- microsite/package.json | 1 + microsite/src/css/customTheme.css | 8 ++++++++ microsite/yarn.lock | 1 + 5 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/features/software-templates/testing-scaffolder-alpha.md b/docs/features/software-templates/testing-scaffolder-alpha.md index c0b97e897c..1b0368f29c 100644 --- a/docs/features/software-templates/testing-scaffolder-alpha.md +++ b/docs/features/software-templates/testing-scaffolder-alpha.md @@ -197,9 +197,9 @@ You will need to change the import for `FieldValidation` to point at the new `re ```ts /* highlight-remove-next-line */ -- import { FieldValidation } from '@rjsf/core'; +import { FieldValidation } from '@rjsf/core'; /* highlight-add-next-line */ -+ import { FieldValidation } from '@rjsf/utils; +import { FieldValidation } from '@rjsf/utils; import { KubernetesValidatorFunctions } from '@backstage/catalog-model'; export const entityNamePickerValidation = ( diff --git a/microsite/docusaurus.config.js b/microsite/docusaurus.config.js index 025c773a9c..8a9fe6fd9b 100644 --- a/microsite/docusaurus.config.js +++ b/microsite/docusaurus.config.js @@ -16,6 +16,11 @@ // @ts-check +/** @type{import('prism-react-renderer').PrismTheme} **/ +// @ts-ignore +const prismTheme = require('prism-react-renderer/themes/vsDark'); +prismTheme.plain.backgroundColor = '#232323'; + /** @type {import('@docusaurus/types').Config} */ module.exports = { title: 'Backstage Software Catalog and Developer Platform', @@ -266,10 +271,11 @@ module.exports = { searchParameters: {}, }, prism: { + theme: prismTheme, magicComments: [ // Extend the default highlight class name { - className: 'theme-code-block-highlighted-line', + className: 'code-block-highlight-line', line: 'highlight-next-line', block: { start: 'highlight-start', end: 'highlight-end' }, }, diff --git a/microsite/package.json b/microsite/package.json index cb71d5a25a..70b1aa86ad 100644 --- a/microsite/package.json +++ b/microsite/package.json @@ -35,6 +35,7 @@ "@swc/core": "^1.3.36", "clsx": "^1.1.1", "docusaurus-plugin-sass": "^0.2.3", + "prism-react-renderer": "^1.3.5", "react": "^17.0.2", "react-dom": "^17.0.2", "sass": "^1.57.1", diff --git a/microsite/src/css/customTheme.css b/microsite/src/css/customTheme.css index 4ba7f1df86..f216762418 100644 --- a/microsite/src/css/customTheme.css +++ b/microsite/src/css/customTheme.css @@ -75,4 +75,12 @@ border-left: 3px solid rgba(255, 0, 0, 0.5); } +.code-block-highlight-line { + background-color: rgba(255, 255, 255, 0.08); + display: block; + margin: 0 calc(-1 * var(--ifm-pre-padding)); + padding: 0 var(--ifm-pre-padding); + border-left: 3px solid rgb(255, 255, 255, 0.5); +} + /* #endregion */ diff --git a/microsite/yarn.lock b/microsite/yarn.lock index a9db81ead4..a6393e7386 100644 --- a/microsite/yarn.lock +++ b/microsite/yarn.lock @@ -3738,6 +3738,7 @@ __metadata: docusaurus-plugin-sass: ^0.2.3 js-yaml: ^4.1.0 prettier: ^2.6.2 + prism-react-renderer: ^1.3.5 react: ^17.0.2 react-dom: ^17.0.2 replace: ^1.2.2 From 1b9fa3440cd5fa6ae07d5245a87efe8234dc5280 Mon Sep 17 00:00:00 2001 From: Paul Schultz Date: Fri, 10 Mar 2023 11:03:37 -0600 Subject: [PATCH 2/3] Update README Signed-off-by: Paul Schultz --- microsite/README.md | 157 ++++++++++++++++++++++++-------------------- 1 file changed, 86 insertions(+), 71 deletions(-) diff --git a/microsite/README.md b/microsite/README.md index 723baa1a54..5c1b0c1678 100644 --- a/microsite/README.md +++ b/microsite/README.md @@ -1,6 +1,6 @@ # Backstage Documentation -This folder holds the service and configuration that runs Backstage's documentation hosted at https://backstage.io. +This folder holds the service and configuration that runs Backstage's documentation hosted at . It pulls content in from the [root `/docs`](../docs/) folder and builds it into the resulting HTML web site. @@ -20,13 +20,13 @@ Testing the web site locally is a great way to see what final website will look ## Installation -``` +```bash $ yarn install ``` ## Local Development -``` +```bash $ yarn start ``` @@ -34,7 +34,7 @@ This command starts a local development server and opens up a browser window. Mo ## Build -``` +```bash $ yarn build ``` @@ -107,30 +107,30 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e 1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`: -```md ---- -id: newly-created-doc -title: This Doc Needs To Be Edited ---- + ```md + --- + id: newly-created-doc + title: This Doc Needs To Be Edited + --- -My new content here.. -``` + My new content here.. + ``` -1. Refer to that doc's ID in an existing sidebar in `website/sidebars.json`: +2. Refer to that doc's ID in an existing sidebar in `website/sidebars.json`: -```javascript -// Add newly-created-doc to the Getting Started category of docs -{ - "docs": { - "Getting Started": [ - "quick-start", - "newly-created-doc" // new doc here - ], - ... - }, - ... -} -``` + ```javascript + // Add newly-created-doc to the Getting Started category of docs + { + "docs": { + "Getting Started": [ + "quick-start", + "newly-created-doc" // new doc here + ], + ... + }, + ... + } + ``` For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation) @@ -138,30 +138,30 @@ For more information about adding new docs, click [here](https://docusaurus.io/d 1. Make sure there is a header link to your blog in `website/siteConfig.js`: -`website/siteConfig.js` + `website/siteConfig.js` -```javascript -headerLinks: [ - ... - { blog: true, label: 'Blog' }, - ... -] -``` + ```javascript + headerLinks: [ + ... + { blog: true, label: 'Blog' }, + ... + ] + ``` 2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`: -`website/blog/2018-05-21-New-Blog-Post.md` + `website/blog/2018-05-21-New-Blog-Post.md` -```markdown ---- -author: Frank Li -authorURL: https://twitter.com/foobarbaz -authorFBID: 503283835 -title: New Blog Post ---- + ```markdown + --- + author: Frank Li + authorURL: https://twitter.com/foobarbaz + authorFBID: 503283835 + title: New Blog Post + --- -Lorem Ipsum... -``` + Lorem Ipsum... + ``` For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog) @@ -169,43 +169,44 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e 1. Add links to docs, custom pages or external links by editing the `headerLinks` field of `website/siteConfig.js`: -`website/siteConfig.js` + `website/siteConfig.js` -```javascript -{ - headerLinks: [ - ... - /* you can add docs */ - { doc: 'my-examples', label: 'Examples' }, - /* you can add custom pages */ - { page: 'help', label: 'Help' }, - /* you can add external links */ - { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' }, - ... - ], - ... -} -``` + ```javascript + { + headerLinks: [ + ... + /* you can add docs */ + { doc: 'my-examples', label: 'Examples' }, + /* you can add custom pages */ + { page: 'help', label: 'Help' }, + /* you can add external links */ + { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' }, + ... + ], + ... + } + ``` For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation) ### Adding custom pages 1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`: -1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: -`website/siteConfig.js` +2. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: -```javascript -{ - headerLinks: [ - ... - { page: 'my-new-custom-page', label: 'My New Custom Page' }, - ... - ], - ... -} -``` + `website/siteConfig.js` + + ```javascript + { + headerLinks: [ + ... + { page: 'my-new-custom-page', label: 'My New Custom Page' }, + ... + ], + ... + } + ``` Learn more about [Docusaurus custom pages](https://docusaurus.io/docs/en/custom-pages). @@ -217,3 +218,17 @@ Full documentation can be found on the [Docusaurus website](https://docusaurus.i - If you want to make images zoomable on click, add the `data-zoomable` attribute to your `img` element. - In a docs or blog `.md` file, convert `![This is image](/microsite/static/img/code.png)` syntax to `This is image` + +- Code block line highlighting uses [custom magic comments](https://docusaurus.io/docs/markdown-features/code-blocks#custom-magic-comments). Currently, we have the following magic comments: + - Highlight line(s) + - `highlight-next-line` + - `highlight-start` + - `highlight-end` + - Add line(s) + - `highlight-add-next-line` + - `highlight-add-start` + - `highlight-add-end` + - Remove line(s) + - `highlight-remove-next-line` + - `highlight-remove-start` + - `highlight-remove-end` From b7319793cea6cdeb5d99fb633a02702074191c83 Mon Sep 17 00:00:00 2001 From: Paul Schultz Date: Fri, 10 Mar 2023 11:04:38 -0600 Subject: [PATCH 3/3] Update README Signed-off-by: Paul Schultz --- microsite/README.md | 131 ++++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 65 deletions(-) diff --git a/microsite/README.md b/microsite/README.md index 5c1b0c1678..26c25dc175 100644 --- a/microsite/README.md +++ b/microsite/README.md @@ -107,30 +107,30 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e 1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`: - ```md - --- - id: newly-created-doc - title: This Doc Needs To Be Edited - --- + ```md + --- + id: newly-created-doc + title: This Doc Needs To Be Edited + --- - My new content here.. - ``` + My new content here.. + ``` 2. Refer to that doc's ID in an existing sidebar in `website/sidebars.json`: - ```javascript - // Add newly-created-doc to the Getting Started category of docs - { - "docs": { - "Getting Started": [ - "quick-start", - "newly-created-doc" // new doc here - ], - ... - }, - ... - } - ``` + ```javascript + // Add newly-created-doc to the Getting Started category of docs + { + "docs": { + "Getting Started": [ + "quick-start", + "newly-created-doc" // new doc here + ], + ... + }, + ... + } + ``` For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation) @@ -138,30 +138,30 @@ For more information about adding new docs, click [here](https://docusaurus.io/d 1. Make sure there is a header link to your blog in `website/siteConfig.js`: - `website/siteConfig.js` + `website/siteConfig.js` - ```javascript - headerLinks: [ - ... - { blog: true, label: 'Blog' }, - ... - ] - ``` + ```javascript + headerLinks: [ + ... + { blog: true, label: 'Blog' }, + ... + ] + ``` 2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`: - `website/blog/2018-05-21-New-Blog-Post.md` + `website/blog/2018-05-21-New-Blog-Post.md` - ```markdown - --- - author: Frank Li - authorURL: https://twitter.com/foobarbaz - authorFBID: 503283835 - title: New Blog Post - --- + ```markdown + --- + author: Frank Li + authorURL: https://twitter.com/foobarbaz + authorFBID: 503283835 + title: New Blog Post + --- - Lorem Ipsum... - ``` + Lorem Ipsum... + ``` For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog) @@ -169,23 +169,23 @@ For more information about blog posts, click [here](https://docusaurus.io/docs/e 1. Add links to docs, custom pages or external links by editing the `headerLinks` field of `website/siteConfig.js`: - `website/siteConfig.js` + `website/siteConfig.js` - ```javascript - { - headerLinks: [ - ... - /* you can add docs */ - { doc: 'my-examples', label: 'Examples' }, - /* you can add custom pages */ - { page: 'help', label: 'Help' }, - /* you can add external links */ - { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' }, - ... - ], - ... - } - ``` + ```javascript + { + headerLinks: [ + ... + /* you can add docs */ + { doc: 'my-examples', label: 'Examples' }, + /* you can add custom pages */ + { page: 'help', label: 'Help' }, + /* you can add external links */ + { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' }, + ... + ], + ... + } + ``` For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation) @@ -195,18 +195,18 @@ For more information about the navigation bar, click [here](https://docusaurus.i 2. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: - `website/siteConfig.js` + `website/siteConfig.js` - ```javascript - { - headerLinks: [ - ... - { page: 'my-new-custom-page', label: 'My New Custom Page' }, - ... - ], - ... - } - ``` + ```javascript + { + headerLinks: [ + ... + { page: 'my-new-custom-page', label: 'My New Custom Page' }, + ... + ], + ... + } + ``` Learn more about [Docusaurus custom pages](https://docusaurus.io/docs/en/custom-pages). @@ -217,6 +217,7 @@ Full documentation can be found on the [Docusaurus website](https://docusaurus.i ## Additional notes - If you want to make images zoomable on click, add the `data-zoomable` attribute to your `img` element. + - In a docs or blog `.md` file, convert `![This is image](/microsite/static/img/code.png)` syntax to `This is image` - Code block line highlighting uses [custom magic comments](https://docusaurus.io/docs/markdown-features/code-blocks#custom-magic-comments). Currently, we have the following magic comments: