smapiot / pidoc

Tools for generating a dynamic documentation experience like for docs.piral.io :robot:.

pidoc ·

A collection of tools and utiltiies for making a documentation page using Piral (and more). Examples using pidoc:

• pidoc.js.org
• docs.piral.io
• docs.piral.cloud
• anglesharp.github.io

A full documentation of this can be found here or online as a website already using pidoc.

Using the pidoc Application

This is best-suited if you just want to bring some documentation to a dynamic website.

(tbd)

Configuration

Place a file called docs.config.json in the project folder where pidoc is being run. It should be adjacent to the package.json.

{
  "title": "Doc Title",
  "description": "The description for the documentation.",
  "author": "your-orga",
  "branch": "main",
  "repositoryUrl": "https://github.com/your-orga/your-repo",
  "rootDir": ".",
  "outputDir": "./dist/docs",
  "skipEditLabel": false,
  "changelogFile": "./CHANGELOG.md",
  "sass": {
    "variables": "./src/global.scss"
  },
  "styles": [
    "./src/styles.css"
  ],
  "components": {
    "logo": "./src/Logo.tsx",
    "infoBar": "./src/InfoBar.tsx",
    "breadcrumbs": "./src/Breadcrumbs.tsx",
    "footer": "./src/Footer.tsx",
    "header": "./src/Header.tsx",
    "notFoundPage": "./src/NotFoundPage.tsx"
  },
  "pages": {
    "/imprint": "./src/ImprintPage.tsx"
  },
  "helpers": {
    "setup": "./src/setup.ts",
    "filter": "./src/filter.ts",
    "plugins": "./src/piralPlugins.ts",
    "requestPilets": "./src/requestPilets.ts"
  },
  "redirects": {
    "/": "/chapterName"
  },
  "sitemap": {
    "chapterName": {
      "title": "Chapter 1",
      "sections": []
    }
  }
}

Commands

These commands are available when using the pidoc library.

Building

A documentation page can be built using

pidoc build

Watching

A documentation page can be watched using

pidoc watch

Emulator

An emulator package can be built using

pidoc sdk

Sitemap Structure

The structure of a sitemap is as follows:

interface SingleSection {
  title: string;
  links: SitemapItem | Array<SitemapItem>;
}

type GenerateContent = CustomGenerator | StandardGenerator;

interface StandardGenerator {
  generator: 'markdown' | 'types';
  segment: string;
  dir: string;
  exclude?: string;
  include?: string;
}

interface CustomGenerator {
  generator: 'custom';
  path: string;
}

type SitemapItem = GenerateContent | SingleSection;

interface Sitemap {
  [chapterName: string]: {
    title: string;
    sections: Array<SitemapItem>;
  };
}

Using the @pidoc/core Library

This is best-suited if you already have a project using piral (or other libraries like piral-core). For more information on Piral visit the GitHub repository or the official homepage.

Installation

You can add the tool by installing it via NPM:

npm i @pidoc/core --save-dev

A couple of peer dependencies also need to be resolved. If can install all peer dependencies using:

npm i piral-core piral-cli piral-cli-webpack5 react react-dom react-router-dom --save-dev

License

pidoc is released using the MIT license. For more information see the license file.