piral-docs-tools ·

The tools for making the documentation page of the Piral project. You can find it at docs.piral.io.

Installation

You can add the tool by installing it via NPM:

npm i piral-docs-tool --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-parcel react react-dom react-router-dom --save-dev

Configuration

Place a file called docs.config.json in the project folder where piral-docs 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",
    "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

Building

A documentation page can be built using

piral-docs build

Watching

A documentation page can be watched using

piral-docs watch

Emulator

An emulator package can be built using

piral-docs 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>;
  };
}

License

Thest tools are released using the MIT license. For more information see the license file.