Repository Website Generator (repository-website-generator)

Generates a Next.js static website by converting markdown to html

Install

npm install @makerx/repository-website-generator --save-dev

Usage

The repository website can be generated by running the following command

 npx repository-website-generator

Tip: Make it more discoverable add it to the package.json scripts collection

"scripts": {
  "generate-website": "npx repository-website-generator"
}

Testing

An easy way of testing the generated website is to use the http-server NPM package.

Install http-server

npm install --save-dev http-server

Add the following script to the package.json file

"scripts": {
  "serve-generated-website": "http-server -c-1 ./out"
}

Then build and launch the website

npx repository-website-generator && npm run serve-generated-website

Miscellaneous Pages

Miscellaneous pages can be enabled by setting the following configuration option.

  "miscellaneousPages": {
    "path": "/public-pages"
  },

Any markdown pages added to the /public-pages directory will be included in the build.

A miscellaneous markdown page has a special format to allow page related configuration settings. The format is:

---
title: Test Page
slug: test-page
menuIndex: 1
---

## A sub-title

The title property is to set the page title when showing the page.

The slug controls the link to the page. The links for miscellaneous pages are rooted. For this example, in the page above, the link would be http://localhost:3000/test-page.

The menuIndex is an optional property. Setting it allows for the control of the miscellaneous page link position.

Code Docs

Currently, only code docs generated by typedoc are supported.

To add typedoc to a solution the follow steps can be taken.

Enable code doc support in website-generator.json file

  "codeDocs": {
    "path": "/code-docs"
  },

Install the packages:

npm install typedoc, typedoc-plugin-markdown --save-dev

Then add a script entry:

"scripts": {
  "generate-doc": "typedoc",
}

And lastly, add the typedoc.json configuration file:

{
  "entryPoints": ["pages/", "shared/", "components/"],
  "entryPointStrategy": "expand",
  "out": "code-docs",
  "plugin": ["typedoc-plugin-markdown"],
  "theme": "default",
  "cleanOutputDir": true,
  "githubPages": false,
  "readme": "none",
  "entryDocument": "code-docs.md",
  "publicPath": "/"
}

Note: the out path for the doc generator must match the codeDocs path defined in the generator configuration.

Configuration options

The configuration file is a json file named website-generator.json, and must be placed at the same level as the package.json file.

Starting configuration file

{
  "outPath": "/out",
  "rootPath": null,
  "readmeFileName": null,
  "title": "My Package name",
  "titleSuperscript": "Proudly built and maintained by [MakerX](https://makerx.com.au)",
  "author": null,
  "name": null,
  "description": null,
  "gitHubUrl": null,
  "soeTags": null,
  "assetsPath": null,
  "miscellaneousPages": null,
  "codeDocs": null,
  "theme": {
    "iconLogo": "/theme/makerx-icon.png",
    "imageLogo": "/theme/makerx-logo.png",
    "imageLogoLink": "https://makerx.com.au"
  },
  "attribution": []
}

Example configuration file

{
  "outPath": "/out",
  "rootPath": null,
  "readmeFileName": null,
  "title": "TS Type Helpers",
  "titleSuperscript": "Proudly built and maintained by [MakerX](https://makerx.com.au)",
  "author": null,
  "name": null,
  "description": null,
  "gitHubUrl": null,
  "soeTags": null,
  "assetsPath": "/public-assets",
  "miscellaneousPages": {
    "path": "/public-pages"
  },
  "codeDocs": {
    "path": "/code-docs"
  },
  "theme": {
    "iconLogo": "/theme/makerx-icon.png",
    "imageLogo": "/theme/makerx-logo.png",
    "imageLogoLink": "https://makerx.com.au"
  },
  "attribution": [
    {
      "group": "Referenced packages",
      "title": "react",
      "description": "React is a JavaScript library for creating user interfaces.",
      "license": "MIT",
      "link": "github.com/facebook/react"
    },
    {
      "group": "Referenced packages",
      "title": "react-dropzone",
      "description": "Simple React hook to create a HTML5-compliant drag'n'drop zone for files.",
      "license": "MIT",
      "link": "https://github.com/react-dropzone/react-dropzone"
    }
  ]
}

outPath (Required)

Where the built site will be copied to.

rootPath (Optional)

The root path for the reference repository.

Note: By default the root path value defaults to /

readmeFileName (Optional)

The name of the main markdown file that will become in the index content.

Note: By default the readme file name value is README.md

title (Required)

The title of the repository website.

titleSuperscript (Required)

The superscript that is rendered with the title.

author (Optional)

The author of the package.

Note: By default the author is referenced from the package.json field author

name (Optional)

The name of the package.

Note: By default the author is referenced from the package.json field name

description (Optional)

The description of the package.

Note: By default the author is referenced from the package.json field description

gitHubUrl (Optional)

The GitHub URL link.

Note: By default the author is referenced from the package.json field description

soeTags (Optional)

The description of the package.

Note: By default the author is referenced from the package.json field repository.url

assetsPath (Optional)

A directory containing assets.

miscellaneousPages (Optional)

The folder containing the miscellaneous markdown files.

See adding miscellaneous pages

codeDocs (Optional)

The folder containing the code doc markdown files.

See adding code docs

theme (Required)

Theme is an object with the following properties.

theme.iconLogo (Required)

The icon logo is shown on the index page next to the H1 title.

theme.imageLogo (Required)

The image logo is shown on all pages in the footer.

theme.imageLogoLink (Required)

The link for the image logo.

Attribution

Is the collection holding additional attribution references which are shown on the attribution page.

The following properties are available per attribution reference

attribution[].group (optional)

An optional group name. All references of the same group are shown together. The group name is shown once.

attribution[].title (required)

The title of the reference.

attribution[].license (required)

The license of the reference.

attribution[].description (optional)

An optional description of the reference.

attribution[].link (optional)

An optional link to the reference.