mirror of
https://github.com/Unleash/unleash.git
synced 2025-10-27 11:02:16 +01:00
130 lines
5.4 KiB
Markdown
130 lines
5.4 KiB
Markdown
# Website
|
|
|
|
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
|
|
|
|
## Installation
|
|
|
|
In a terminal, cd into the website folder of the locally cloned unleash repository and then start the installation.
|
|
|
|
```console
|
|
cd unleash/website
|
|
yarn install
|
|
```
|
|
|
|
## Generate OpenAPI docs
|
|
|
|
```console
|
|
yarn generate
|
|
```
|
|
|
|
Generate the Open API docs that live at Reference documentation > APIs > OpenAPI
|
|
|
|
## Local Development
|
|
|
|
Before running the docs the first time, you'll need to generate external documentation, as described in the [generate OpenAPI docs](#generate-openapi-docs) section.
|
|
|
|
```console
|
|
yarn start
|
|
```
|
|
|
|
Start a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
|
|
|
|
## Build
|
|
|
|
```console
|
|
yarn build
|
|
```
|
|
|
|
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
|
|
|
## Cleaning dependencies and caches
|
|
|
|
If you're upgrading many dependencies, it's always good to delete the `node_modules` directory, refresh `yarn.lock` and clean the various caches.
|
|
|
|
```console
|
|
rm -rf node_modules
|
|
rm -rf .docusaurus
|
|
rm -rf docs/reference/api/unleash
|
|
rm -rf yarn.lock
|
|
touch yarn.lock
|
|
```
|
|
|
|
## Search
|
|
|
|
This website uses Algolia DocSearch v3 with a dedicated Algolia application and a hosted crawler. All configuration is managed directly through the Algolia dashboard.
|
|
|
|
### Search prioritization
|
|
|
|
Conceptual and reference documentation pages should rank over specific API endpoints, while still allowing Algolia's relevance algorithm to find the most accurate results.
|
|
|
|
#### The configuration
|
|
|
|
**Inside the Algolia crawler**:
|
|
The crawler configuration has been updated to look for a <meta name="search_priority" content="..." /> tag in the HTML of each page.
|
|
It extracts the numerical value and saves it as a priority attribute on the search record. Pages without this tag are automatically assigned a default priority of 0.
|
|
Algolia is configured to use the `priority` attribute for custom ranking in descending order.
|
|
|
|
**Within the docs**:
|
|
We have a reusable React component, `<SearchPriority />` -> `src/components/SearchPriority.jsx`. This component provides a simple shortcut to add the correct <meta> tag to any .mdx page.
|
|
|
|
For high priority pages, use `<SearchPriority level="high" />`. For pages referencing deprecated features use `<SearchPriority level="noindex" />`.
|
|
For autogenerated pages, use `searchPriority: 'high'` key-value pair in the document definition of the file (works at the root level or for individual subpages). See `website/remote-content/edge-proxy.js` as an example.
|
|
|
|
## Troubleshooting
|
|
|
|
### `TypeError: source_default(...).bold is not a function`
|
|
|
|
If you get an error like this, it's probably due to a formatting issue within one of the markdown files. It could be
|
|
|
|
- unescaped angle brackets (markdown will try to parse `<your-key>` (when it's not quoted) as HTML, which breaks the build)
|
|
- incorrectly formatted titles or missing pieces of files
|
|
- a lot of other stuff.
|
|
|
|
```console
|
|
Component Figure was not imported, exported, or provided by MDXProvider as global scope
|
|
|
|
TypeError: source_default(...).bold is not a function
|
|
[ERROR] Unable to build website for locale en.
|
|
```
|
|
|
|
This error is very hard to debug, but there is a trick that appears to work (as shared in [this discussion on docusaurus' repo](https://github.com/facebook/docusaurus/issues/7686#issuecomment-1486771382)):
|
|
|
|
In `node_modules/@docusaurus/core/lib/client/serverEntry.js`, remove all references to `chalk`. You can use a regex replace for that, by replacing `chalk(\w|\.)+` with the empty string.
|
|
|
|
Depending on your editor, that regex might need more escapes. For instance, here's a command to run with `evil-ex` in Emacs:
|
|
|
|
```
|
|
%s/chalk\(\w\|\.\)+//g
|
|
```
|
|
|
|
For macOS `sed`, it'd be:
|
|
|
|
```shell
|
|
sed -i '' 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
|
|
```
|
|
|
|
For GNU `sed`:
|
|
|
|
```shell
|
|
sed -i 's/chalk\(\w\|\.\)\+//g' node_modules/@docusaurus/core/lib/client/serverEntry.js
|
|
```
|
|
|
|
That might turn your error into something like this:
|
|
|
|
```console
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/change-requests.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/feature-types.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/frontend-api.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/maintenance.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/notifications.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/personal-access-tokens.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/segments.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/service-accounts.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/telemetry.
|
|
[ERROR] Docusaurus server-side rendering could not render static page with path /reference/api/unleash/unstable.
|
|
Component Figure was not imported, exported, or provided by MDXProvider as global scope
|
|
|
|
Error: Unexpected: cant find current sidebar in context
|
|
[ERROR] Unable to build website for locale en.
|
|
```
|