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.

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

Changes from Dhub #3

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
3,117 changes: 2,771 additions & 346 deletions CHANGELOG.md

Large diffs are not rendered by default.

8 changes: 2 additions & 6 deletions website/docs/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https
| `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
| `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |

:::important

Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.

:::
:::important Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production. :::

:::info Development over network

Expand All @@ -76,7 +72,7 @@ There are multiple ways to obtain a certificate. We will use [mkcert](https://gi
HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
```

4. Open `https://localhost:3000/`
1. Open `https://localhost:3000/`

### `docusaurus build [siteDir]` {#docusaurus-build-sitedir}

Expand Down
2 changes: 1 addition & 1 deletion website/docs/docusaurus-core.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ import ErrorBoundaryTestButton from "@site/src/components/ErrorBoundaryTestButto

:::tip

To see it in action, click here: <ErrorBoundaryTestButton/>
To see it in action, click here: <ErrorBoundaryTestButton />

:::

Expand Down
10 changes: 4 additions & 6 deletions website/docs/static-assets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,22 +88,20 @@ In CSS, the `url()` function is commonly used to reference assets like fonts and

The `static/font/Caroline.otf` asset will be loaded by the bundler.

:::warning important takeaway

One important takeaway: **never hardcode your base URL!** The base URL is considered an implementation detail and should be easily changeable. All paths, even when they look like URL slugs, are actually file paths.
:::warning important takeaway One important takeaway: **never hardcode your base URL!** The base URL is considered an implementation detail and should be easily changeable. All paths, even when they look like URL slugs, are actually file paths.

If you find the URL slug mental model more understandable, here's a rule of thumb:

- Pretend you have a base URL like `/test/` when writing JSX so you don't use an absolute URL path like `src="/img/thumbnail.png"` but instead `require` the asset.
- Pretend it's `/` when writing Markdown or CSS so you always use absolute paths without the base URL.

:::
- Pretend it's `/` when writing Markdown or CSS so you always use absolute paths without the base URL. :::

## Caveats {#caveats}

Keep in mind that:

- By default, none of the files in the `static` folder will be post-processed, hashed, or minified.

- However, as we've demonstrated above, we are usually able to convert them to `require` calls for you so they do get processed. This is good for aggressive caching and better user experience.

- Missing files referenced via hard-coded absolute paths will not be detected at compilation time and will result in a 404 error.
- By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.com/). Since Jekyll will discard any files that begin with `_`, it is recommended that you disable Jekyll by adding an empty file named `.nojekyll` file to your `static` directory if you are using GitHub pages for hosting.
7 changes: 3 additions & 4 deletions website/docs/styling-layout.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,7 @@ If you can't find a way to create a robust CSS selector, please [report your cus
:::

<details>

<summary>Exhaustive list of stable class names</summary>
<summary>Exhaustive list of stable class names</summary>

```mdx-code-block
import ThemeClassNamesCode from '!!raw-loader!@site/../packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts';
Expand Down Expand Up @@ -231,7 +230,7 @@ To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 p
npm install --save docusaurus-plugin-sass sass
```

2. Include the plugin in your `docusaurus.config.js` file:
1. Include the plugin in your `docusaurus.config.js` file:

```js title="docusaurus.config.js"
module.exports = {
Expand All @@ -242,7 +241,7 @@ module.exports = {
};
```

3. Write and import your stylesheets in Sass/SCSS as normal.
1. Write and import your stylesheets in Sass/SCSS as normal.

### Global styles using Sass/SCSS {#global-styles-using-sassscss}

Expand Down
12 changes: 3 additions & 9 deletions website/docs/swizzling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,7 @@ In practice, swizzling permits to **swap a theme component with your own impleme
- [**Wrapping**](#wrapping): creates a **wrapper** around the original theme component, which you can **enhance**

<details>

<summary>Why is it called swizzling?</summary>
<summary>Why is it called swizzling?</summary>

**The name comes from Objective-C and Swift-UI**: [method swizzling](https://pspdfkit.com/blog/2019/swizzling-in-swift/) is the process of changing the implementation of an existing selector (method).

Expand Down Expand Up @@ -100,11 +99,7 @@ After swizzling a component, **restart your dev server** in order for Docusaurus

:::

:::warning Prefer staying on the safe side

Be sure to understand [which components are **safe to swizzle**](#what-is-safe-to-swizzle). Some components are **internal implementation details** of a theme.

:::
:::warning Prefer staying on the safe side Be sure to understand [which components are **safe to swizzle**](#what-is-safe-to-swizzle). Some components are **internal implementation details** of a theme. :::

:::info

Expand Down Expand Up @@ -227,8 +222,7 @@ export default function BlogPostItemWrapper(props) {
Some theme components are **internal implementation details** of a theme. Docusaurus allows you to swizzle them, but it **might be risky**.

<details>

<summary>Why is it risky?</summary>
<summary>Why is it risky?</summary>

Theme authors (including us) might have to update their theme over time: changing the component props, name, file system location, types... For example, consider a component that receives two props `name` and `age`, but after a refactor, it now receives a `person` prop with the above two properties. Your component, which still expects these two props, will render `undefined` instead.

Expand Down