Skip to content
This repository was archived by the owner on Nov 16, 2022. It is now read-only.

Commit 26dbdf7

Browse files
DanilAndreevDanilAndreev
committed
[CreatingMaterialDocs] Added tutorial.
1 parent bacd958 commit 26dbdf7

File tree

4 files changed

+352
-119
lines changed

4 files changed

+352
-119
lines changed

‎src/pages/Tutorials/CreatingMaterialDocs/CreatingMaterialDocs.md‎

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
# Создание Material Docs
2+
## Создание проекта
3+
Создадим новый проект с помощью утилиты __create-react-app__. Подробнее об этой утилите [здесь](https://reactjs.org/docs/create-a-new-react-app.html).
4+
Мы назвали проект _material-docs-example-project_ :).
5+
```{"type": "code", "theme": "darcula", "language": "javascript"}
6+
$ npx create-react-app material-docs-example-project
7+
```
8+
## Установка Material Material Docs
9+
После того, как проект создан - надо установить Material Docs.
10+
С помощью __yarn__:
11+
```{"type": "code", "theme": "darcula", "language": "javascript"}
12+
$ yarn add @material-docs/core
13+
```
14+
С помощью __npm__:
15+
```{"type": "code", "theme": "darcula", "language": "javascript"}
16+
$ npm install @material-docs/core
17+
```
18+
### Настройка index.html
19+
Material Docs использует шрифт _Roboto_, давайте установим его.
20+
В директории __public__ добавьте в файл ___index.html___ следующее:
21+
```{"type": "code", "theme": "darcula", "language": "javascript"}
22+
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />
23+
```
24+
Файл ___index.html___ должен выглядеть примерно так:
25+
```{"type": "expansion-code", "theme": "darcula", "language": "javascript", "name": "index.html"}
26+
<!DOCTYPE html>
27+
<html lang="en">
28+
<head>
29+
<meta charset="utf-8" />
30+
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
31+
<meta name="viewport" content="width=device-width, initial-scale=1" />
32+
<meta name="theme-color" content="#000000" />
33+
<meta
34+
name="description"
35+
content="Web site created using create-react-app"
36+
/>
37+
<link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
38+
<link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
39+
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />
40+
<title>React App</title>
41+
</head>
42+
<body>
43+
<noscript>You need to enable JavaScript to run this app.</noscript>
44+
<div id="root"></div>
45+
</body>
46+
</html>
47+
```
48+
### Удаление ненужных файлов
49+
Вы можете удалить файлы:
50+
* App.css
51+
* App.test.js
52+
* App.js
53+
54+
Они нам не понадобятся.
55+
## Создание документации
56+
### Базовая структура
57+
![Basic structure](&&BasicStructureImage)
58+
Для начала, создадим в файле __index.js__ следующую структуру:
59+
##### index.js
60+
```{"type": "code", "theme": "darcula", "language": "javascript"}
61+
import React from 'react';
62+
import ReactDOM from 'react-dom';
63+
import * as serviceWorker from './serviceWorker';
64+
65+
import DocsLayout from "@material-docs/core/components/DocsLayout";
66+
import DocsPages from "@material-docs/core/components/DocsPages";
67+
import DocsMenu from "@material-docs/core/components/DocsMenu";
68+
import AutoDocsMenu from "@material-docs/core/components/AutoDocsMenu";
69+
70+
ReactDOM.render(
71+
<React.StrictMode>
72+
<DocsLayout
73+
name={"My documentation"}
74+
version={"1.0.0-alpha"}
75+
logo={"http://material-docs.com/static/media/logo.5a237c82.svg"}
76+
keywords={["my", "test", "documentation"]}
77+
description={"This is an example documentation for Material Docs framework."}
78+
author={"Danil Andreev"}
79+
>
80+
<DocsMenu>
81+
<AutoDocsMenu />
82+
</DocsMenu>
83+
<DocsPages>
84+
85+
</DocsPages>
86+
</DocsLayout>
87+
</React.StrictMode>,
88+
document.getElementById('root')
89+
);
90+
91+
serviceWorker.unregister();
92+
```
93+
Это базовая структура для приложения Material Docs.
94+
Мы указали следующие параметры для компонента DocsLayout:
95+
* ___name___ - Название документации.
96+
* ___version___ - версия документации.
97+
* ___logo___ - путь к картинке логотипу.
98+
* ___keywords___ - Ключевые слова страницы для того, чтоб поисковые движки могли проиндексировать её.
99+
* ___description___ - описание страницы для метаданных.
100+
* ___author___ - Имя автора.
101+
102+
Больше информации о компонентах вы можете получить в разделе __Component APIs__ этой документации. К примеру,
103+
вот [__документация компонента__ ```DocsLayout```]().
104+
105+
В компоненте ```DocsMenu``` хранится информация о структуре меню. Компонент ```AutoDocsMenu``` позволяет
106+
не задумываться о создании меню вручную.
107+
108+
Внутри компонента ```DocsPages``` будут находиться страницы.
109+
110+
## Создание страницы
111+
![Page image](&&PageAboutMeImage)
112+
Приступим к написанию страницы с информацией. Создадим страницу о себе:
113+
##### index.html
114+
```{"type": "code", "theme": "darcula", "language": "javascript"}
115+
import React from 'react';
116+
import ReactDOM from 'react-dom';
117+
import * as serviceWorker from './serviceWorker';
118+
119+
import DocsLayout from "@material-docs/core/components/DocsLayout";
120+
import DocsPages from "@material-docs/core/components/DocsPages";
121+
import DocsMenu from "@material-docs/core/components/DocsMenu";
122+
import AutoDocsMenu from "@material-docs/core/components/AutoDocsMenu";
123+
import DocsPage from "@material-docs/core/components/DocsPage";
124+
import H1 from "@material-docs/core/components/H1";
125+
import H3 from "@material-docs/core/components/H3";
126+
import Markdown from "@material-docs/core/components/Markdown";
127+
import Image from "@material-docs/core/components/Image";
128+
import Code from "@material-docs/core/components/Code";
129+
import H4 from "@material-docs/core/components/H4";
130+
131+
ReactDOM.render(
132+
<React.StrictMode>
133+
<DocsLayout
134+
name={"My documentation"}
135+
version={"1.0.0-alpha"}
136+
logo={"http://material-docs.com/static/media/logo.5a237c82.svg"}
137+
keywords={["my", "test", "documentation"]}
138+
description={"This is an example documentation for Material Docs framework."}
139+
author={"Danil Andreev"}
140+
>
141+
<DocsMenu>
142+
<AutoDocsMenu />
143+
</DocsMenu>
144+
<DocsPages>
145+
<DocsPage
146+
name={"Page about me"}
147+
searchLabel={"Danil Andreev | About me"}
148+
searchDescription={"This is a page about my person."}
149+
searchTags={["me", "info", "danil", "andreev", "programmer"]}
150+
>
151+
<H1>My name is Danil Andreev</H1>
152+
<H3>This is a page about my history.</H3>
153+
<Markdown>Hello, my name is __Danil Andreev__, I am a programmer from Kiev, Ukraine.</Markdown>
154+
<Image src={"https://cdnb.artstation.com/p/users/avatars/000/449/963/large/fc6a568b26ecfe1fe02f6dc60da732ae.jpg?1587936613"}/>
155+
<H4>I will show you a piece of code</H4>
156+
<Code>
157+
$ Hello darkness my old friend
158+
</Code>
159+
</DocsPage>
160+
</DocsPages>
161+
</DocsLayout>
162+
</React.StrictMode>,
163+
document.getElementById('root')
164+
);
165+
166+
serviceWorker.unregister();
167+
```
168+
### Создание страничного компонента
169+
Для того, чтоб было удобнее редактировать страницы мы рекомендуем создавать страничные компоненты и размещать их в
170+
отдельных файлах. Например, обернем нашу страницу в компонент:
171+
```{"type": "expansion-code", "theme": "darcula", "language": "javascript", "name": "FirstPage.js"}
172+
import React from "react";
173+
import DocsPage from "@material-docs/core/components/DocsPage";
174+
import H1 from "@material-docs/core/components/H1";
175+
import H3 from "@material-docs/core/components/H3";
176+
import Markdown from "@material-docs/core/components/Markdown";
177+
import Image from "@material-docs/core/components/Image";
178+
import H4 from "@material-docs/core/components/H4";
179+
import Code from "@material-docs/core/components/Code";
180+
181+
export default function FirstPage() {
182+
return (
183+
<DocsPage
184+
name={"Page about me"}
185+
searchLabel={"Danil Andreev | About me"}
186+
searchDescription={"This is a page about my person."}
187+
searchTags={["me", "info", "danil", "andreev", "programmer"]}
188+
>
189+
<H1>My name is Danil Andreev</H1>
190+
<H3>This is a page about my history.</H3>
191+
<Markdown>Hello, my name is __Danil Andreev__, I am a programmer from Kiev, Ukraine.</Markdown>
192+
<Image src={"https://cdnb.artstation.com/p/users/avatars/000/449/963/large/fc6a568b26ecfe1fe02f6dc60da732ae.jpg?1587936613"}/>
193+
<H4>I will show you a piece of code</H4>
194+
<Code>
195+
$ Hello darkness my old friend
196+
</Code>
197+
</DocsPage>
198+
199+
);
200+
}
201+
```
202+
```{"type": "expansion-code", "theme": "darcula", "language": "javascript", "name": "index.js"}
203+
import React from 'react';
204+
import ReactDOM from 'react-dom';
205+
import * as serviceWorker from './serviceWorker';
206+
207+
import DocsLayout from "@material-docs/core/components/DocsLayout";
208+
import DocsPages from "@material-docs/core/components/DocsPages";
209+
import DocsMenu from "@material-docs/core/components/DocsMenu";
210+
import AutoDocsMenu from "@material-docs/core/components/AutoDocsMenu";
211+
import FirstPage from "./pages/FirstPage";
212+
213+
ReactDOM.render(
214+
<React.StrictMode>
215+
<DocsLayout
216+
name={"My documentation"}
217+
version={"1.0.0-alpha"}
218+
logo={"http://material-docs.com/static/media/logo.5a237c82.svg"}
219+
keywords={["my", "test", "documentation"]}
220+
description={"This is an example documentation for Material Docs framework."}
221+
author={"Danil Andreev"}
222+
>
223+
<DocsMenu>
224+
<AutoDocsMenu />
225+
</DocsMenu>
226+
<DocsPages>
227+
<FirstPage/>
228+
</DocsPages>
229+
</DocsLayout>
230+
</React.StrictMode>,
231+
document.getElementById('root')
232+
);
233+
234+
serviceWorker.unregister();
235+
```
236+
### Создадим еще одну страницу
237+
```{"type": "expansion-code", "theme": "darcula", "language": "javascript", "name": "SecondPage.js"}
238+
import React from "react";
239+
import DocsPage from "@material-docs/core/components/DocsPage";
240+
import H1 from "@material-docs/core/components/H1";
241+
import Table from "@material-docs/core/components/Table";
242+
import TableRow from "@material-docs/core/components/TableRow";
243+
import TableCell from "@material-docs/core/components/TableCell";
244+
import TableHead from "@material-docs/core/components/TableHead";
245+
import TableBody from "@material-docs/core/components/TableBody";
246+
import H3 from "@material-docs/core/components/H3";
247+
248+
export default function SecondPage() {
249+
return (
250+
<DocsPage
251+
name={"Features page"}
252+
searchLabel={"Features are cool!"}
253+
searchDescription={"This is a page about features."}
254+
searchTags={["page", "feature", "amazing"]}
255+
>
256+
<H1>This is a feature page</H1>
257+
<H3 noDivider>Table</H3>
258+
<Table>
259+
<TableHead>
260+
<TableRow>
261+
<TableCell>Action</TableCell>
262+
<TableCell>Dog</TableCell>
263+
<TableCell>Human</TableCell>
264+
</TableRow>
265+
</TableHead>
266+
<TableBody>
267+
<TableRow>
268+
<TableCell>Can speak</TableCell>
269+
<TableCell>No</TableCell>
270+
<TableCell>Yes</TableCell>
271+
</TableRow>
272+
<TableRow>
273+
<TableCell>Can eat</TableCell>
274+
<TableCell>Yes</TableCell>
275+
<TableCell>Yes</TableCell>
276+
</TableRow>
277+
<TableRow>
278+
<TableCell>Can run very fast</TableCell>
279+
<TableCell>No</TableCell>
280+
<TableCell>Yes</TableCell>
281+
</TableRow>
282+
</TableBody>
283+
</Table>
284+
</DocsPage>
285+
);
286+
}
287+
```
288+
### Группирование страниц
289+
Для того, чтоб автоматическое меню могло создавать группы страниц, их надо оборачивать в компонент ```PagesGroup```.
290+
Давайте обернём страницу FirstPage в группу "My Group"
291+
```{"type": "expansion-code", "theme": "darcula", "language": "javascript", "name": "index.js"}
292+
import React from 'react';
293+
import ReactDOM from 'react-dom';
294+
import * as serviceWorker from './serviceWorker';
295+
296+
import DocsLayout from "@material-docs/core/components/DocsLayout";
297+
import DocsPages from "@material-docs/core/components/DocsPages";
298+
import DocsMenu from "@material-docs/core/components/DocsMenu";
299+
import AutoDocsMenu from "@material-docs/core/components/AutoDocsMenu";
300+
import FirstPage from "./pages/FirstPage";
301+
import SecondPage from "./pages/SecondPage";
302+
import PagesGroup from "@material-docs/core/components/PagesGroup";
303+
304+
ReactDOM.render(
305+
<React.StrictMode>
306+
<DocsLayout
307+
name={"My documentation"}
308+
version={"1.0.0-alpha"}
309+
logo={"http://material-docs.com/static/media/logo.5a237c82.svg"}
310+
keywords={["my", "test", "documentation"]}
311+
description={"This is an example documentation for Material Docs framework."}
312+
author={"Danil Andreev"}
313+
>
314+
<DocsMenu>
315+
<AutoDocsMenu />
316+
</DocsMenu>
317+
<DocsPages>
318+
<PagesGroup name={"My Group"}>
319+
<FirstPage/>
320+
</PagesGroup>
321+
<SecondPage/>
322+
</DocsPages>
323+
</DocsLayout>
324+
</React.StrictMode>,
325+
document.getElementById('root')
326+
);
327+
328+
serviceWorker.unregister();
329+
```
330+
### Переадресация между страницами
331+
У компонента ```Link``` есть параметр ___page___, в который передается путь внутренней странице.
332+
Так как страница, на которую мы хотим сделать переадресацию находится в группе __My Group__ - путь будет выглядеть так:
333+
```
334+
["My Group", "Page about me"]
335+
```
336+
#### SecondPage.js
337+
```{"type": "code", "theme": "darcula", "language": "javascript"}
338+
<Link page={["My Group", "Page about me"]}>Redirect to Page About Me</Link>
339+
```
340+
341+
#### Исходники на GitHub
342+
Вы можете найти этот пример на GitHub [здесь](https://github.com/material-docs/material-docs-example-project/tree/creating-material-docs)

‎src/pages/Tutorials/CreatingMaterialDocs/images/BasicStructureImage.png‎

48 KB
Loading

‎src/pages/Tutorials/CreatingMaterialDocs/images/PageAboutMeImage.png‎

234 KB
Loading

0 commit comments

Comments
 (0)