Repository Website Generator (repository-website-generator)
Generates a Next.js static website by converting markdown to html
!npm packagenpm-imgnpm-url !Build Statusbuild-imgbuild-url !Downloadsdownloads-imgdownloads-url !Issuesissues-imgissues-url !Semantic Releasesemantic-release-imgsemantic-release-url
Install
npm install @makerx/repository-website-generator --save-dev
Usage
The repository website can be generated by running the following commandnpx 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:
```text
title: Test Page slug: test-pagemenuIndex: 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](https://typedoc.org/) are supported.
To add typedoc to a solution the follow steps can be taken.
Enable code doc support in website-generator.json file
```text
"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 namedwebsite-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