Создайте свою собственную библиотеку компонентов пользовательского интерфейса React (3): написание документов

Преамбула

Эта серия статей будет постоянно обновляться по мере развития автора.

Ожидаемое содержимое следующее:

Создайте собственную библиотеку компонентов пользовательского интерфейса React:

(один):От v0.0,0 до v0.0.1

(два):Создайте домашнюю страницу

(3): Написание документов (эта статья)

(4): Сотрите детали

(5): продвижение, реклама, итерация

<= to be continue =

Я могу получить доступ к своей библиотеке компонентов здесь:BB-color

и адрес npm:BB-color

соглашение

В этой серии статей максимально подробно рассматривается каждый шаг, каждый файл и каждое обновление.
В этом цикле статей старт всего проекта основан на официально предоставленномcreat-react-appСделайте реактивную сборку, и все будет разработано с использованием последней версии библиотеки.
- create-react-app v2.1.1
- react v16.7.0
- webpack v4.19.1
- babel 7+
- node v10.15.0
- docz v0.13.7

Основные знания

Базовое понимание React
будет использовать Git
Базовые знания JavaScript, CSS и т.д.

текст начинается

отправная точка

Необходимое содержание библиотеки UI-компонентов — написание документов, и это тоже первоочередная задача. мы будем использоватьdoczчтобы помочь нам в разработке документов.

Примечание 1:

doczВы можете быстро создать документацию для использования и демонстрации библиотеки компонентов пользовательского интерфейса React, которая используетMarkdownрасширение грамматикиMDX(Введите компоненты React в Markdown и компоненты рендеринга) для написания документов, в настоящее время поддерживает только реакцию. Больше можно найти наgithubа такжеофициальная документацияпросматривать

Готов к работе

Выполните следующую команду, чтобы установить необходимые зависимости

npm install --save-dev docz docz-theme-default docz-plugin-css @emotion/core

Заметка 2:

docz: docz основная часть, требуется

docz-theme-default:docz тема по умолчанию, обязательна

docz-plugin-css: Дополнительные плагины при использовании CSS в документе, не требуются, если CSS не требуется.

@emotion/core: Зависимость от документации, требуется

После завершения установки модифицируем наш package.json

// package.json

{
    ...
    
    "scripts": {
        ...
        
        "docz:dev": "docz dev", 
        "docz:build": "docz build"
    }
    ...
}

писать документацию

мы вsrc/componentsсоздатьhome.mdx

Дополнительная точка знаний A:

Его не обязательно создавать в src, в официальной документации упоминается:

Note that you don't need to follow any strict file architecture. You can just create your .mdx files anywhere in your project.

docz распознает файлы .mdx где угодно, поэтому вы можете писать документацию где угодно. Вы также можете создать еще одну папку docz для хранения ваших файлов документов отдельно, но лично рекомендуется писать в соответствии со структурой каталогов наших компонентов, чтобы мы могли напрямую найти нужный нам контент в последующих модификациях.

// src/components/home.mdx

---
name: 首页
route: /
---

# Hello world

Hello, I'm a mdx file!

затем вsrc/components/buttonсоздан вbutton.mdx

// src/components/button/button.mdx

---
name: Button
route: /button
---

import { Playground, PropsTable } from 'docz'
import Button from './index.js'

# Button

<PropsTable of={Button} />

## Basic usage

<Playground>
 <Button>Click me</Button>
</Playground>

На этом написание части документации заканчивается, а дальше идет написание конфигурации

Создать в корневом каталогеdoczrc.js

// doczrc.js

import { css } from 'docz-plugin-css'

export default {
  title: 'BB Color',
  description: 'A Design UI library for React',
  plugins: [
    css({
      preprocessor: 'postcss'
    })
  ]
}

После выполнения вышеуказанных операций вся директория проекта станет вот такой

Тогда просто бегиnpm startМол, выполняем через gitbashnpm run docz:dev

Если проблем нет, вы увидите следующую страницу

Поздравляем, вы успешно создали собственную документацию. Вы можете нажать «Домой» и «Кнопку» слева, чтобы просмотреть определенный контент.

В настоящее время мы сделали только самую основную часть, и в этой статье будет объяснено только самое основное построение контента, Каждая деталь, каждый документ будет передан вам и вашему творчеству для завершения.

*Экспорт пакетов (опционально)

Упаковка и экспорт относительно просты, напрямуюnpm run docz:build, ты сможешь.docz/distНайдите свои статические файлы здесь. Если вы хотите упаковать в другие папки, вы можетеdoczrc.jsнастроить

Вы можете найти связанную конфигурацию здесь:

Woohoo.doc в .site/intro duct IO…

Я сохраняю этот шаг как есть и не занимаюсь им.

После выполнения пакета это будет выглядеть так

./.docz/distОн хранит файлы, которые мы упаковали

Отправить код

Перед отправкой кода измените его.gitignore

// .gitignore

...

/.docz

...

Тогда это нормальная подача

git add .
git commit -m '文档创建'
git push -u origin master

так далее! Это еще не конец!

После того, как код отправлен, мы еще не можем войти на страницу документации, нам также нужно развернуть наш код документации

развернуть код

Файлы, которые мы упаковали, являются статическими файлами, и нам нужно развернуть их отдельно.

Может вы думаете, создать док-файл в docs, поместить файлы в dist в doc, как домашнюю страницу, напрямую войти через страницы github.

Но, к сожалению, этот метод неосуществим.

Здесь есть проблема. Ссылка на файл ресурсов, упакованный docz, основана на абсолютном пути к корню маршрута.

Например, яdocs/Локальная служба запускается по пути по адресуhttp://127.0.0.1/, обычно мы можем получить доступ кdocs/index.html. Когда мы посещаем страницу документации, адрес меняется наhttp://127.0.0.1/doc, мы также можем получить доступdocs/doc/index.htmlНо все ресурсы не могут быть загружены, потому что указанные ресурсы будут найдены в корневом каталоге (docs) запускаемого сервера, а не в относительном пути./docs/docПосмотри внутри.

Веб-сайт, который мы создали через страницы github, имеет следующий адрес:https://bb-color.github.io/BB-color/существуетhttps://bb-color.github.ioНужных нам статических файлов здесь нет.

Вот 2 способа развернуть наш код документа.

Купите сервер, доменное имя, отправьте наш код на сервер и получите доступ с доменного имени.
использоватьNetlifyПомогите нам развернуть.

Развертывание с помощью Netlify

Netlify — отличный и простой инструмент, который позволяет вам развертывать ваше приложение в автоматическом режиме, запуская развертывание при каждом нажатии из вашей ветки за считанные секунды.и это бесплатно

Войтиnetlify,использоватьgithub регистрация вход

После успешного входа он автоматически перейдет на личную домашнюю страницу, а затем будет следовать инструкциям красной стрелки на рисунке ниже.

Затем просто выберите файл в нашу библиотеку компонентов

Далее нужно установить 3 места,

Первый - выбрать ветку, мы можем выбрать Мастера
Во-вторых, введите команду сборки, введите команду сборки документа, которую мы установили в package.json.
Третий ввод Когда команда сборки документа выполняется, путь к упакованному файлу, потому что я не изменил путь, введите значение по умолчанию.docz/distВот и все,

затем нажмитеdeploy siteразвернуть

Он будет автоматически развернут во время первого шага на изображении ниже, просто дождитесь завершения первого шага.

После завершения развертывания вы можете получить доступ к развернутому веб-сайту по красной стрелке. Если вас не устраивает доменное имя, вы можете настроить собственное доменное имя с помощью желтой стрелки.

Нам нужно установить это только один раз, и каждый раз, когда мы будем отправлять код в будущем, Netlify будет автоматически развертывать для нас последний код.

представить снова

Перед отправкой измените нашу домашнюю страницу, чтобы наша домашняя страница могла перейти на нашу страницу документации.

git tag -a 'v0.0.3' -m '文档构建'
git push origin v0.0.3
git add .
git commit -m '文档引用'
git push -u origin master

Поздравляем, библиотека компонентов пользовательского интерфейса с домашней страницей и документацией готова! !

конец

Я думал, что самая важная серия из трех пишет в течение длительного времени, я не ожидал, что печень так быстро, ведь есть и другие давления, заставляли меня завершить этот раздел как можно скорее, 23333

После этого четвертая и пятая главы являются дополнительными главами, которые не так важны, как первые три главы, и писаться после этого будут не так быстро. 2333

Если есть какое-то неуместное или отсутствующее место, я надеюсь указать на это в области комментариев и сообщить рационально.

Если вам нужно перепечатать, пожалуйста, укажите автора и оригинальный адрес

Добавить Автора

оригинал:nuggets.capable/post/684490…