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.