docz README

The project's README from github.com/pedronauck/docz. As one markdown file: README.md.

Docz

Docz makes it easy to write and publish beautiful interactive documentation for your code. Create MDX files showcasing your code and Docz turns them into a live-reloading, production-ready site.

Why?

Documenting code is one of the most important and time-consuming tasks when developing software.

A lot of time is spent on building and maintaining custom documentation sites.

Docz enables you to quickly create a live-reloading, SEO-friendly, production-ready documentation site with MDX and customize the look, feel and behavior when required by leveraging GatsbyJS and Gatsby theme shadowing.

Getting started

Start by adding docz as a dependency to your project with Yarn or npm:

$ yarn add docz # react react-dom

# or

$ npm install docz # react react-dom

Note: react and react-dom will not be installed automatically. You'll have to install them yourself.

Then, create .mdx files anywhere in your project:

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

import { Playground, Props } from 'docz'
import Button from './Button'

# Button

<Props of={Button} />

## Basic usage

<Playground>
  <Button type="submit">Click me</Button>
  <Button>No, click me</Button>
</Playground>

And a Button component Button.jsx:

import React from 'react'
import t from 'prop-types'

const Button = ({ children, type }) => <button type={type}>{children}</button>

Button.propTypes = {
  /**
   * This is a description for this prop.
   * Button type.
   */
  type: t.oneOf(['button', 'submit', 'reset']),
}
Button.defaultProps = {
  type: 'button',
}
export default Button

Finally, run:

yarn docz dev

This starts a local development server and opens your documentation site in the browser.

Build

yarn docz build generates a static site in .docz/dist/.

Try it with yarn docz serve or by serving the generated site with your favorite static file server (e.g. npx serve .docz/dist).

You can have yarn docz build emit to a different directory by providing a path to the dest field in your doczrc.js or from the command line: yarn docz build --dest docs-site-directory.

Deploying

The output of docz consists of static assets only. This allows you to deploy your generated docz site with any static site hosting provider you'd like.

Start by building your site with yarn docz build, if you haven't provided a dest flag to your config then you will find your generated files in .docz/dist to copy to the server.

Examples

You can check the complete list of docz examples here.

Used by

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Contributing

All kinds of contributions are very welcome and appreciated!

If you want to contribute time to docz then here's a list of suggestions to get you started:

  1. Star the project on GitHub.
  2. Help people in the issues by sharing your knowledge and experience.
  3. Find and report issues.
  4. Submit pull requests to help solve issues or add features.
  5. Influence the future of docz with feature requests.

If you're looking for a place to start make sure to check issues tagged with the good first issue label:

Good First Issue

Read the Contributing Guide before you open a pull request.

You can also sponsor us via OpenCollective to help secure docz's future.

Open Collective

docz (pedronauck/docz)

Searching Database…

23.6K ·GitHub
Docz
archived
Что это такое?Docz — это инструмент для документации: вы пишете MDX-файлы, в которых показываете свой код, а он превращает их в сайт с документацией с автосохранением при изменениях, готовый к выкладке в продакшен.
Docz — это библиотека компонентов или инструмент сборки?Это скорее инструмент сборки, а не библиотека компонентов: вы добавляете docz как зависимость в свой проект, пишете .mdx-файлы, и Docz генерирует из них полноценный сайт с документацией.
Как запустить сайт с документацией в моём проекте?Установите docz через Yarn или npm, создайте .mdx-файлы в любом месте проекта, затем запустите команду docz — она поднимет локальный dev-сервер и откроет вашу документацию в браузере.
Docz сам устанавливает React?Нет — react и react-dom не устанавливаются автоматически, поэтому их нужно добавить в проект самостоятельно.
Docz ещё поддерживается?Нет. Репозиторий на GitHub заархивирован, поэтому Docz доступен только для чтения и больше не получает обновлений — это стоит знать, прежде чем выбирать его для нового проекта.
Docz работает с React Native?Да — «with react native» — один из официальных примеров, перечисленных в README, вместе с настройками для styled-components, TypeScript, react-router, flow и других.
Почему стоит использовать Docz, а не делать собственный сайт с документацией?Документирование кода — одна из самых важных и затратных по времени задач в разработке, и команды тратят много времени на создание и поддержку собственных сайтов с документацией — Docz заменяет эту работу на MDX-файлы и готовый сайт на Gatsby.
What are similar projects?fumadocs, docusaurus, react-styleguidist, chakra-ui, core, styled-components, mdx-deck, nextra
Which topics is it in?zero-configuration, docs, documentation-tool, style-guide, js, mdx, static-site-generator, design-system, theme, ui-components, documentation, ui
Creator
pedronauck
Size
9.8 MB
Stars
23.6K
Updated
CommitNov 21Releasev2.4.0Jun 23
Age
8y
Commits · 90 Days