@fa-repo/shard-docs NPM

Shard Docs

A simple engine for organising and viewing docs written in JSX.

Usage example

Install

This package relies on react router for routing.

npm install @fa-repo/shard-docs react-router-dom

Basic usage

// documentation.js
import React from "react";
import { render } from "react-dom";
import { HashRouter } from "react-router-dom";
import ShardDocs from "@fa-repo/shard-docs";
import "@fa-repo/shard-docs/dist/shard-docs.css";

const source = [
  { title: "Install", document: <><h1>Install</h1></> },
  { title: "Basic usage", document: <><h1>Basic usage</h1></> },
  {
    title: "Examples",
    children: [
      { title: "Use case A", document: <><h1>Use case A</h1></> },
      { title: "Use case B", document: <><h1>Use case B</h1></> }
    ]
  },
  { title: "Github", externalLink: "https://github.com" },
]

render(
  <HashRouter>
    <ShardDocs
      title="ShardDocs demo"
      description="A description describing the purpose of the docs."
      source={source}
    />
  </HashRouter>,
  document.getElementById("root")
);

API

<ShardDocs
  /**
   * Assign docs a title. Title appears at the top of the sidebar.
   * @string
   * @default ""
  */
  title="App title"
  /**
   * Describe intention of docs. Appears below the title.
   * @optional
   * @string
   * @default ""
  */
  description="App description"
  /**
   * Add a prefix to all routes. E.g. "/docs/".
   * @optional
   * @string
   * @default "/"
  */
  basePath="/docs/"
  /**
   * "Built with Shard Docs" is shown by default at the bottom of the sidebar. This option hides it.
   * @optional
   * @boolean
   * @default false
  */
  hideBuiltWithShardDocs={true}
  /**
   * Data is fed in through the source prop. Scroll down for an explanation of the schema.
   * @array
   * @default []
  */
  source={[
    {
      title: "Essentials",
      children: [
        { title: "Get started", document: <p>Lorem ipsum dolor sit amet..</p> }
      ]
    }
  ]}
/>

Source schema

The input source value is made up of a variety of items that affect how the sidebar menu is rendered and the paths to documents and folders are generated.

Each item has a common title property. The combination of the subsequent properties defines their types.

Let's take a look at the different items:

document: Represents a document endpoint.

  {
    /**
     * Document title
     * @string
    */
    title: "Install",
    /**
     * Document content
     * @jsx
    */
    document: <h1>Install</h1>
  }

folder: Contains any array with any number of items.

  {
    /**
     * Folder title.
     * @optional
     * @string
    */
    title: "Install",
    /**
     * Folder items. Can contain any type of node.
     * @array
    */
    children: [ /* items */ ]
  }

externalLink: A link that opens in a new tab.

  {
    /**
     * Link title.
     * @string
    */
    title: "Github",
    /**
     * Link href.
     * @string
    */
    externalLink: "http://www.github.com"
  }

Write docs with MDX

Documents are composed from JSX which offers a lot of power but the syntax can get unwieldy. MDX makes writing docs a breaze by combining the syntaxes of JSX and markdown. Setting up mdx-js will enabled this feature. Totally recommended!

JSX:

<>
  <h1>Title</h1>
  <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
  labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores
  et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.</p>
  <h2>Examples</h2>
  <h3>Hello world</h3>
  <Example sourceCode={`/* example source code*/`}>
    <App>
  </Example>
</>

MDX:

# Title

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores
et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

## Examples

### Hello world

<Example sourceCode={`/* example source code*/`}>
  <App>
</Example>