Skip to content

Commit 9798beb

Browse files
garronejgarronej
committed
Put the documentation in a GitBook
1 parent 528a72a commit 9798beb

File tree

1 file changed

+18
-171
lines changed

1 file changed

+18
-171
lines changed

‎README.md‎

Lines changed: 18 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -1,176 +1,23 @@
11
<p align="center">
2-
<i>React implementation of the <a href="https://www.systeme-de-design.gouv.fr/">DSFR</a></i>
2+
<img src="https://user-images.githubusercontent.com/6702424/80216211-00ef5280-863e-11ea-81de-59f3a3d4b8e4.png">
3+
</p>
4+
<p align="center">
5+
<i> React implementation of the <a href="https://www.systeme-de-design.gouv.fr/">DSFR</a>! </i>
6+
<br>
7+
<br>
8+
<a href="https://github.com/codegouvfr/dsfr-react/actions">
9+
<img src="https://github.com/codegouvfr/dsfr-react/workflows/ci/badge.svg?branch=main">
10+
</a>
11+
<a href="https://www.npmjs.com/package/tss-react">
12+
<img src="https://img.shields.io/npm/dm/tss-react">
13+
</a>
14+
<a href="https://github.com/codegouvfr/dsfr-react/blob/main/LICENSE">
15+
<img src="https://img.shields.io/npm/l/tss-react">
16+
</a>
17+
</p>
18+
<p align="center">
19+
<a href="https://etalab-2.gitbook.io/dsfr-react/">Documentation</a>
320
</p>
4-
5-
WIP
6-
7-
# Install
8-
9-
```bash
10-
yarn add dsfr-react
11-
```
12-
13-
`package.json` (Optional if you are using Next.js):
14-
15-
```diff
16-
"scripts": {
17-
+ "postinstall": "update_dsfr_static_resources"
18-
}
19-
```
20-
21-
> `update_dsfr_static_resources` is a `bin` script of `dsfr-react` that copies `@gouvfr/dsfr/dist` to `public/dsfr`
22-
23-
`.gitignore`:
24-
25-
```diff
26-
+ /public/dsfr
27-
```
28-
29-
## Single page applications
30-
31-
If you are using [Create React App](https://create-react-app.dev/) or [Vite](https://vitejs.dev/) or a similar SPA framework.
32-
33-
`public/index.html` ( or `/index.html` depending of your Framework )
34-
35-
```diff
36-
<!DOCTYPE html>
37-
<html>
38-
<head>
39-
+ <link rel="apple-touch-icon" href="/dsfr/favicon/apple-touch-icon.png" />
40-
+ <link rel="icon" href="/dsfr/favicon/favicon.svg" type="image/svg+xml" />
41-
+ <link rel="shortcut icon" href="/dsfr/favicon/favicon.ico" type="image/x-icon" />
42-
+ <link rel="manifest" href="/dsfr/favicon/manifest.webmanifest" crossorigin="use-credentials" />
43-
44-
+ <!-- For preventing https://fonts.google.com/knowledge/glossary/fout -->
45-
+ <!-- Be eco friendly, only preload the fonts variant you actually use, you can see in the network tab
46-
+ of your browser dev tools what are the font varian downloaded initially. -->
47-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Light.woff2" as="font" crossorigin="anonymous" />
48-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Light_Italic.woff2" as="font" crossorigin="anonymous" />
49-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Regular.woff2" as="font" crossorigin="anonymous" />
50-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Regular_Italic.woff2" as="font" crossorigin="anonymous" />
51-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Medium.woff2" as="font" crossorigin="anonymous" />
52-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Medium_Italic.woff2" as="font" crossorigin="anonymous" />
53-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Bold.woff2" as="font" crossorigin="anonymous" />
54-
+ <link rel="preload" href="/dsfr/fonts/Marianne-Bold_Italic.woff2" as="font" crossorigin="anonymous" />
55-
+ <link rel="preload" href="/dsfr/fonts/Spectral-Regular.woff2" as="font" crossorigin="anonymous" />
56-
+ <link rel="preload" href="/dsfr/fonts/Spectral-ExtraBold.woff2" as="font" crossorigin="anonymous" />
57-
58-
+ <link rel="stylesheet" href="/dsfr/dsfr.min.css"/>
59-
</head>
60-
```
61-
62-
> NOTE: If you are using CRA and if you are hosting your app under a subpath (`package.json` -> `"homepage": "https://my-site.gouv/a/sub/path"`) you need to include
63-
> `%PUBLIC_URL%` [like so](https://github.com/codegouvfr/dsfr-react/blob/c13d1066b188a509d5808aa6c87722bedc35f21f/src/test/apps/cra/public/index.html#L10-L21) in the URL.
64-
65-
`src/index.tsx`
66-
67-
```diff
68-
+import { startReactDsfr } from "dsfr-react";
69-
+startReactDsfr({ "defaultColorScheme": "system" });
70-
```
71-
72-
## Next.js
73-
74-
`next.config.js`:
75-
76-
```diff
77-
module.exports = {
78-
reactStrictMode: true,
79-
+ webpack: config => {
80-
+
81-
+ config.module.rules.push({
82-
+ test: /\.(woff2|webmanifest)$/,
83-
+ type: "asset/resource"
84-
+ });
85-
+
86-
+ return config;
87-
+ }
88-
}
89-
```
90-
91-
Create a [`_app.tsx` (or `_app.js`)](https://nextjs.org/docs/advanced-features/custom-app) file:
92-
93-
```tsx
94-
import { withDsfr } from "dsfr-react/lib/nextJs";
95-
import DefaultApp from "next/app";
96-
import "dsfr-react/dsfr/dsfr.css";
97-
98-
export default withDsfr(
99-
DefaultApp, // You can, of course, provide your custom App in place of the default if you have one
100-
{
101-
"defaultColorScheme": "system",
102-
// Preloading fonts prevent from https://fonts.google.com/knowledge/glossary/fout
103-
// Be eco friendly, only preload the fonts variant you actually use,
104-
// you can see in the network tab of your browser dev tools what are
105-
// the font varian downloaded initially.
106-
"preloadFonts": ["Marianne-Bold", "Marianne-Regular", "Marianne-Medium"]
107-
}
108-
);
109-
```
110-
111-
# Importing assets
112-
113-
Let's say, [in the DSFR documentation](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/parametres-d-affichage), you come
114-
across the following HTML code.
115-
116-
```html
117-
<!-- Official documentation code, don't copy paste that -->
118-
<svg>
119-
<use xlink:href="../../../dist/artwork/dark.svg#artwork-minor" />
120-
</svg>
121-
```
122-
123-
Because the `npx update_dsfr_static_resources` (supposing you ran it) copied
124-
all the assets into `public/dsfr/` you can always translate the above HTML code into:
125-
126-
```tsx
127-
// ❌ DON'T
128-
<svg>
129-
<use xlinkHref="/dsfr/artwork/dark.svg#artwork-minor#artwork-minor" />
130-
</svg>
131-
```
132-
133-
It will work but don't do that, it's not the maintainable nor the more efficient way.
134-
Write this instead:
135-
136-
```tsx
137-
// ✅ DO
138-
import artworkDarkSvgUrl from "dsfr-react/dsfr/artwork/dark.svg";
139-
140-
<svg>
141-
<use xlinkHref={`${artworkDarkSvgUrl}#artwork-minor`} />
142-
</svg>;
143-
```
144-
145-
Depending of your webpack config the way you import assets may vary.
146-
For example, by default in a Next.js project, you'll get the `.svg` url
147-
this way (Same thing for `.png`, `.ico` and other image format):
148-
149-
```diff
150-
-import artworkDarkSvgUrl from "dsfr-react/dsfr/artwork/dark.svg";
151-
+import artworkDarkSvg from "dsfr-react/dsfr/artwork/dark.svg";
152-
153-
<svg>
154-
- <use xlinkHref={`${artworkDarkSvgUrl}#artwork-minor`} />
155-
+ <use xlinkHref={`${artworkDarkSvg.src}#artwork-minor`} />
156-
</svg>;
157-
```
158-
159-
If you are getting TypeScript error while trying to import assets:
160-
161-
Create a `/src/global.d.ts` (or `/global.d.ts` in Next.js):
162-
163-
```typescript
164-
declare module "*.svg" {
165-
declare const url: string;
166-
export default url;
167-
/* In Next.js it will be instead
168-
declare const _default: { src: string; height: number; width: number; };
169-
export default _default;
170-
*/
171-
}
172-
//OR just 'declare module "*.svg";' if you don't know/want to write the actual type.
173-
```
17421

17522
# Development
17623

0 commit comments

Comments
 (0)