diff --git a/README.md b/README.md index db16998..ab4641d 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,25 @@ This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 Inter [cc-by-sa-image]: https://licensebuttons.net/l/by-sa/4.0/88x31.png [cc-by-sa-shield]: https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator. ## Installation - + +Use a supported Node.js LTS release (Node.js 22 or newer) and the Yarn version pinned in +`package.json`. The installed Docusaurus version requires Node.js 20 or newer, even though +this repository's `engines` field still lists an older minimum. + +Enable [Corepack](https://yarnpkg.com/corepack) so the pinned Yarn version is used: + ```bash -yarn +corepack enable +yarn install --immutable ``` +If `corepack` is not available in your Node.js installation, install it with +`npm install --global corepack` first. Do not run `yarn set version stable` in this repository +unless you intend to upgrade its package manager. + ## Local Development ```bash @@ -34,6 +45,9 @@ yarn build This command generates static content into the `build` directory and can be served using any static contents hosting service. +Preview the production build locally with `yarn serve`. Run `yarn typecheck` to check TypeScript; +there are currently known errors in shared components, so report any new diagnostics separately. + ## Community homepage and theme The [homepage](src/pages/index.tsx) highlights the knowledge base, plugin directory, and ways to @@ -79,16 +93,11 @@ If its dimensions change, update `og:image:width` and `og:image:height` in ## Deployment -Using SSH: - -```bash -USE_SSH=true yarn deploy -``` - -Not using SSH: - -```bash -GIT_USER= yarn deploy -``` +This repository deploys to **Cloudflare Pages**, not GitHub Pages. The +[Publish workflow](.github/workflows/publish.yml) builds and deploys changes pushed to `main`. +Pull requests from the same repository receive preview deployments. For forked pull requests, +a maintainer must review the changes and add the `🚀request-deploy` label to request deployment. -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +The workflow requires the `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` repository secrets. +For local work, use `yarn build` and `yarn serve`; `yarn deploy` is Docusaurus's GitHub Pages +deployment command and is not the deployment path for this site. diff --git a/contributing/customisations.mdx b/contributing/customisations.mdx index fff4769..675257a 100644 --- a/contributing/customisations.mdx +++ b/contributing/customisations.mdx @@ -9,9 +9,9 @@ This site has a number of custom features that are not part of Docusaurus out of ### Home Page Components -The home page components are used to break up the content on the home page into sections. Each component is a React component that is rendered on the home page. The components are defined in the `src/components/` directory and are all named `Homepage*` where `*` is the name of the component. +The home page is defined in `src/pages/index.tsx`, with its layout and card styles in `src/pages/index.module.scss`. The curated links, topic cards, and contribution links are maintained there. The older `Homepage*` components in `src/components/` are not used by the current home page. -They will not, generally, be detailed in-depth here unless they are particularly complex. If you need to make changes to the home page, you should look at the components in the `src/components/` directory. +Shared colours, typography, navigation, and light/dark styling are defined in `src/scss/_community-theme.scss`, loaded by `src/scss/custom.scss`. The [repository README](https://github.com/DocusaurusCommunity/website#community-homepage-and-theme) also covers the logo and social share image. ### Documented Components @@ -25,11 +25,15 @@ The `DocusaurusButton` component is a custom button component that is used throu ### Admonition -We run a custom version of the `Admonition` component that is part of Docusaurus. This component is used to display information boxes in the documentation. The custom version of this component is defined in `src/components/Admonition/*`. You'll find in-depth documentation in the Knowledge section of the site on how to "decode" our customised Admonitions or create your own. +We run a custom version of the `Admonition` component that is part of Docusaurus. This component is used to display information boxes in the documentation. The custom version of this component is defined in `src/theme/Admonition/`. You'll find in-depth documentation in the Knowledge section of the site on how to "decode" our customised Admonitions or create your own. -### DocItem\Footer +### DocItem/Footer -We have a customised `DocItem\Footer` component which is the component used to display the footer on the documentation pages. This component is defined in `src/components/DocItem/Footer.tsx`. This component is used to display the footer on the documentation pages. It is a simple component that displays the footer text and the last updated date of the document. Our customised version is inspired by the amazing work of the `unleash` team who [added contributors to their documentation](https://github.com/Unleash/unleash/pull/6900). +The wrapper in `src/theme/DocItem/Footer/index.tsx` keeps the standard Docusaurus document footer and adds a contributor list. Its helper components fetch contributors from the document's GitHub commit history and include any `additionalContributors` from frontmatter. This is inspired by the `unleash` team who [added contributors to their documentation](https://github.com/Unleash/unleash/pull/6900). + +### Logo + +The component in `src/theme/Logo/index.tsx` renders the community mark and two-tone wordmark in the navbar and mobile menu. The logo assets and their light/dark variants are configured in `docusaurus.config.ts`. ## Custom Plugins diff --git a/contributing/index.mdx b/contributing/index.mdx index f40dae0..fcc0c51 100644 --- a/contributing/index.mdx +++ b/contributing/index.mdx @@ -4,4 +4,10 @@ hide_title: true sidebar_position: -999 --- -The contributing documentation is a collection of guides and articles that cover topics related to contributing to the Docusaurus community. This includes guides on how to contribute to the website, the knowledge base, and the Docusaurus project itself. +Found a useful plugin, spotted a mistake, or learned something that might help someone else? Contributions are welcome. + +- [Add a plugin](./plugins.mdx) to the directory, either through the submission form or a pull request. +- Improve a guide or add a new article in the [knowledge base](/knowledge/). Its Markdown and MDX files live in `docs/`. +- Read about the [site's custom functionality](./customisations.mdx) before changing its components or theme. + +Work happens in the [DocusaurusCommunity/website repository](https://github.com/DocusaurusCommunity/website). The [README](https://github.com/DocusaurusCommunity/website#installation) covers local setup and validation. diff --git a/contributing/plugins.mdx b/contributing/plugins.mdx index 377eee9..f626cc1 100644 --- a/contributing/plugins.mdx +++ b/contributing/plugins.mdx @@ -15,7 +15,7 @@ The plugin directory is powered by [`@homotechsual/docusaurus-plugin-showcase`]( ## Create your YAML file -Add a new file to `data/plugins/` named `..yaml`. Use lowercase letters, numbers, and hyphens only. +Add a new file to `data/plugins/` named `..yaml`. Use lowercase letters, numbers, and hyphens in each part, separated by a single dot. The filename should match the entry's `id`. ```yaml # yaml-language-server: $schema=https://docusaurus.community/schema/plugin/1.0.0.json @@ -41,7 +41,7 @@ npmPackages: | `id` | Yes | `author.plugin-name` — must be unique | | `name` | Yes | Display name shown in the directory | | `description` | Yes | Short, one-sentence description | -| `preview` | Yes | URL to a preview image, or `null` to auto-generate | +| `preview` | No | URL to a preview image; omit or set to `null` to auto-generate | | `website` | Yes | Public website or repository URL | | `source` | No | Source code URL — required if the plugin is open source, `null` or omitted if closed source | | `author` | No | Your GitHub username or organisation name | @@ -52,7 +52,9 @@ npmPackages: ### Tags -`search` · `api` · `utility` · `content` · `theme` · `markdown` · `analytics` · `integration` · `seo` · `editing` · `docusaurus` +`search` · `api` · `utility` · `content` · `theme` · `markdown` · `analytics` · `integration` · `seo` · `editing` + +The `favourite` and `docusaurus` tags are reserved for maintainer-curated listings. The automated submission workflow removes these tags from submissions by users without admin or maintain permissions. ## Submit a pull request diff --git a/docs/component-library/existing/Admonitions/index.mdx b/docs/component-library/existing/Admonitions/index.mdx index c99e89e..4d8f184 100644 --- a/docs/component-library/existing/Admonitions/index.mdx +++ b/docs/component-library/existing/Admonitions/index.mdx @@ -193,7 +193,7 @@ This is a security warning This is a security warning ::: -There we have it. We've created a new admonition type and added it to our Docusaurus project. This site features a [number of other admonition types](https://github.com/homotechsual/docusaurus.community/tree/main/src/theme/Admonition) that you can use as a reference for creating your own. +There we have it. We've created a new admonition type and added it to our Docusaurus project. This site features a [number of other admonition types](https://github.com/DocusaurusCommunity/website/tree/main/src/theme/Admonition) that you can use as a reference for creating your own. ## Examples diff --git a/docs/component-library/new/TimeLine/index.mdx b/docs/component-library/new/TimeLine/index.mdx index f5bccea..e68d347 100644 --- a/docs/component-library/new/TimeLine/index.mdx +++ b/docs/component-library/new/TimeLine/index.mdx @@ -18,7 +18,10 @@ The component will create every items in Time line, you will be able to create a The component integrates the Native css [colors variables of Infima ](https://infima.dev/docs/utilities/colors) i invite you look the official documentation to styling your site with Infima and the new documentation on community site (Work in progress !) [CSS Variables](/knowledge/design/css/variables/) - + diff --git a/docs/deployment/cloudflare-pages.mdx b/docs/deployment/cloudflare-pages.mdx index 33f03d7..ac672cb 100644 --- a/docs/deployment/cloudflare-pages.mdx +++ b/docs/deployment/cloudflare-pages.mdx @@ -1,6 +1,6 @@ --- -title: CloudFlare Pages Deployment -description: Deploy Docusaurus to CloudFlare Pages using modern Yarn. +title: Cloudflare Pages Deployment +description: Deploy Docusaurus to Cloudflare Pages using modern Yarn. --- ## Before you start @@ -27,7 +27,7 @@ Do not run `yarn install` yet. We will do that later, after we have configured o Make sure you have committed the `package.json` and `yarn.lock` files to your Git repository before you deploy to CloudFlare Pages. This is because CloudFlare Pages will run `yarn install` for you, and you want to make sure that it installs the same dependencies that you have locally. You should not be pushing your `node_modules` or `build` directories to Git. ::: -So next we want to enable [Corepack](https://yarnpkg.com/corepack), an official [Node.js](https://nodejs.org/) tool, developed alongside [Yarn](https://yarnpkg.com/), that allows you to define your chosen package manager, and version, in your `package.json` file. +Use [Corepack](https://yarnpkg.com/corepack) to select the package manager version recorded in your `package.json`. If your Node.js installation does not include Corepack, install it with `npm install --global corepack` first, then enable it: ```bash corepack enable @@ -53,7 +53,7 @@ yarn start ### Create your CloudFlare Pages project -Deploying your Docusaurus site you CloudFlare pages will require you to have a CloudFlare account. You can use any of CloudFlare's supported repository providers. +Deploying your Docusaurus site to Cloudflare Pages requires a Cloudflare account. You can use any of Cloudflare's supported repository providers. Login to the [CloudFlare Dashboard](https://dash.cloudflare.com/) and click on "Workers and Pages" in the left hand menu. You're then going to select "Create Application", select the "Pages" tab and finally click on "Connect to Git". @@ -71,15 +71,13 @@ Finally, click "Save and Deploy" and your site will be deployed to CloudFlare Pa ### Custom domain -If you want to use a custom domain with your CloudFlare Pages deployment, you can do so by following the [Custom Domain documentation](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/) on the CloudFlare website. +If you want to use a custom domain with your Cloudflare Pages deployment, follow the [custom domain documentation](https://developers.cloudflare.com/pages/configuration/custom-domains/). ### Caching -:::warning[Not yet compatible with modern Yarn] -For reasons passing understanding, CloudFlare, despite adding caching as a beta in 2023 decided not to add support for modern versions of Yarn, instead only supporting the archaic Yarn 1 (classic Yarn) alongside `npm`, `pnpm` and `bun`. Be sure to let their team know how very silly this decision is and how much you'd like to see support for modern Yarn. -::: +Cloudflare Pages supports [build caching](https://developers.cloudflare.com/pages/configuration/build-caching/) on build system V2 or later. Enable it under **Settings > Build > Build cache** in your Pages project. -In order to speed up builds and reduce bandwidth usage, CloudFlare Pages can cache your dependencies between builds. This is enabled from your project settings by selecting the "Builds & deployments" menu item and then clicking "Enable build cache" in the "Build cache (Beta)" section. +The documented Yarn cache location is `.cache/yarn`. Modern Yarn projects can use a different cache directory, so check your configuration rather than assuming all dependencies will be cached. Cloudflare also documents caching Docusaurus build output in `node_modules/.cache`, `.docusaurus`, and `build`. ### Preview deployments diff --git a/docs/design/css/variables/index.mdx b/docs/design/css/variables/index.mdx index 7c6eba7..c7ca10e 100644 --- a/docs/design/css/variables/index.mdx +++ b/docs/design/css/variables/index.mdx @@ -3,7 +3,7 @@ title: CSS Variables description: Common CSS variables used in Docusaurus. --- - + :::warning[Work in Progress] This documentation is a work in progress. If you have any questions or suggestions, please feel free to open an issue on the [Docusaurus Community Website GitHub repository](https://github.com/DocusaurusCommunity/website/issues). diff --git a/docs/index.mdx b/docs/index.mdx index 8673d1c..e6dc0dd 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -14,4 +14,4 @@ The knowledge base is a collection of articles written by the community. It's a ## How to contribute -If you want to contribute to the knowledge base, you can do so by creating a pull request on the [website repository](https://github.com/homotechsual/docusaurus.community). The knowledge base is a collection of Markdown files, so you can create a new file or edit an existing one. +If you want to contribute to the knowledge base, you can do so by creating a pull request on the [website repository](https://github.com/DocusaurusCommunity/website). Articles live in `docs/` as Markdown or MDX files, so you can add a new guide or improve an existing one. diff --git a/package.json b/package.json index 4ef2124..50df3e0 100644 --- a/package.json +++ b/package.json @@ -30,7 +30,7 @@ "@fortawesome/free-solid-svg-icons": "^7.3.0", "@fortawesome/react-fontawesome": "^3.3.1", "@homotechsual/docusaurus-plugin-plausible": "^1.1.1", - "@homotechsual/docusaurus-plugin-showcase": "1.2.0", + "@homotechsual/docusaurus-plugin-showcase": "1.2.3", "@iconify/react": "^6.0.2", "@mdx-js/react": "^3.1.1", "@popperjs/core": "^2.11.8", diff --git a/yarn.lock b/yarn.lock index faf08de..f6d659b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4446,9 +4446,9 @@ __metadata: languageName: node linkType: hard -"@homotechsual/docusaurus-plugin-showcase@npm:1.2.0": - version: 1.2.0 - resolution: "@homotechsual/docusaurus-plugin-showcase@npm:1.2.0" +"@homotechsual/docusaurus-plugin-showcase@npm:1.2.3": + version: 1.2.3 + resolution: "@homotechsual/docusaurus-plugin-showcase@npm:1.2.3" dependencies: "@docusaurus/faster": "npm:^3.10.1" "@popperjs/core": "npm:^2.11.8" @@ -4462,7 +4462,7 @@ __metadata: "@docusaurus/core": ">=3.0.0 <5.0.0" react: ~19.2.7 react-dom: ~19.2.7 - checksum: 10c0/9b3e306de08751df35d76d4cdd1c1eb02460b880e9139b029a039947393a2217e3b96e913f4c766ae10e660edae9475efd045c887e5c2ab1c6f03106a21096d4 + checksum: 10c0/86462b54a857f516abb9a8f8fdf9939bfde51aad47066ab7183d3a2c5f4268adb665fc8a7dda69f0508721aeababea298ef709ab4fa128a8f38de64b07017593 languageName: node linkType: hard @@ -9836,7 +9836,7 @@ __metadata: "@fortawesome/free-solid-svg-icons": "npm:^7.3.0" "@fortawesome/react-fontawesome": "npm:^3.3.1" "@homotechsual/docusaurus-plugin-plausible": "npm:^1.1.1" - "@homotechsual/docusaurus-plugin-showcase": "npm:1.2.0" + "@homotechsual/docusaurus-plugin-showcase": "npm:1.2.3" "@iconify/react": "npm:^6.0.2" "@mdx-js/react": "npm:^3.1.1" "@popperjs/core": "npm:^2.11.8"