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.

1{
2  "title": "Doc Title",
3  "description": "The description for the documentation.",
4  "author": "your-orga",
5  "branch": "main",
6  "repositoryUrl": "https://github.com/your-orga/your-repo",
7  "rootDir": ".",
8  "outputDir": "./dist/docs",
9  "skipEditLabel": false,
10  "changelogFile": "./CHANGELOG.md",
11  "sass": {
12    "variables": "./src/global.scss"
13  },
14  "styles": [
15    "./src/styles.css"
16  ],
17  "components": {
18    "logo": "./src/Logo.tsx",
19    "infoBar": "./src/InfoBar.tsx",
20    "breadcrumbs": "./src/Breadcrumbs.tsx",
21    "footer": "./src/Footer.tsx",
22    "header": "./src/Header.tsx",
23    "notFoundPage": "./src/NotFoundPage.tsx"
24  },
25  "pages": {
26    "/imprint": "./src/ImprintPage.tsx"
27  },
28  "helpers": {
29    "setup": "./src/setup.ts",
30    "filter": "./src/filter.ts",
31    "plugins": "./src/piralPlugins.ts",
32    "requestPilets": "./src/requestPilets.ts"
33  },
34  "redirects": {
35    "/": "/chapterName"
36  },
37  "sitemap": {
38    "chapterName": {
39      "title": "Chapter 1",
40      "sections": []
41    }
42  }
43}

Commands

These commands are available when using the pidoc library.

Building

A documentation page can be built using

1pidoc build

Watching

A documentation page can be watched using

1pidoc watch

Emulator

An emulator package can be built using

1pidoc sdk

Sitemap Structure

The structure of a sitemap is as follows:

1interface SingleSection {
2  title: string;
3  links: SitemapItem | Array<SitemapItem>;
4}
5
6type GenerateContent = CustomGenerator | StandardGenerator;
7
8interface StandardGenerator {
9  generator: 'markdown' | 'types';
10  segment: string;
11  dir: string;
12  exclude?: string;
13  include?: string;
14}
15
16interface CustomGenerator {
17  generator: 'custom';
18  path: string;
19}
20
21type SitemapItem = GenerateContent | SingleSection;
22
23interface Sitemap {
24  [chapterName: string]: {
25    title: string;
26    sections: Array<SitemapItem>;
27  };
28}

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:

1npm i @pidoc/core --save-dev

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

1npm 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.