From 345b5ac6b98626df3025e3cc0e903f2c9719e024 Mon Sep 17 00:00:00 2001 From: Siddhant Agarwal Date: Mon, 7 Jun 2021 12:15:04 +0530 Subject: [PATCH 1/2] feat: Update Readme to add setup details --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 60a00c3..3b89c3d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,70 @@ # Citadel -An extensible static site generator. +Citadel is an extensible static site generator. It takes markdown files and generates html files out if it with the help of pug based templates. The system uses stylus as the css-preprocessor of choice. -## Internal details +## Features + +- Pug based templating engine +- Stylus css preprocess +- Branding, multi-site generation +- Extensibility with plugins +- Reusability (with the help of partials) +- Easy redirects +- Document blacklist support + +## Setup + +Citadel requires a *config* file to be present in the root directory of your project. +The name of the config file can be given through command line as follows +``` +citadel -c +``` + +Default: `config.js` + +## Configuration + +Citadel accepts a config file with an array of config objects. Each config object defines how to build your static site for that particular organisation/brand. +Citadel gives the following configuration options + +| Name | Description | Required | +|-|-|-| +| org | The organisation / brand scope to build the site for. | true | +| basePath | The basePath where the site will be hosted | true | +| publicPath | The publichPath where the site will be accessible | true | +| port | The port on which the site will be available | true | +| src | The path where the source documents are available | true | +| dist | The path where the built documents need to be stored | true | +| layout | The path where the pug templates are available | true | +| css | The path where the stylus files available | true | +| js | The path where the custom js files available | true | +| assets | The path where the source documents are available | true | +| partials | Path to the partials folder where reusable content can be stored | false | +| redirects | The path to the yaml file to setup redirects. Can be a list of files | false | +| rules | Defines the files to exclude from any build | true | +| plugins | Defines a list of plugins | false | + +Sample configuration for an example documentation site: +``` +module.exports = [{ + org: "abc", + basePath: "https://abc.com", + publicPath: "/docs/", + port: 8080, + src: "src/posts", + dist: "dist", + layout: "src/layouts/index.pug", + css: "src/styles/app.styl", + js: "src/app.js", + assets: "src/assets", + partials: "src/partials", + redirects: ["src/redirects.yml"], + rules: [ + -setup/initial-setup // ignore file src/posts/setup/intial-setup (`-` indicates ignore) + ], + plugins: ["plugins/search"], + }], +``` ### Document structure From 49241edcea87af4ac6587e7d715e908815b40f82 Mon Sep 17 00:00:00 2001 From: Siddhant Agarwal Date: Fri, 2 Jul 2021 09:59:05 +0530 Subject: [PATCH 2/2] add usage details (wip) --- README.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3b89c3d..cd4b1db 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,14 @@ Citadel is an extensible static site generator. It takes markdown files and gene - Reusability (with the help of partials) - Easy redirects - Document blacklist support - ## Setup +To install Citadel in your project + +``` + npm install https://github.com/razorpay/citadel +``` + Citadel requires a *config* file to be present in the root directory of your project. The name of the config file can be given through command line as follows ``` @@ -66,9 +71,40 @@ module.exports = [{ }], ``` +## Usage + + +### Layout +The pug template present in the `layout` variable in the `config` will get the following variables + +``` +{ + frontmatter: Object, // The frontmatter defined in each post + href: string, // The url based on the folder structure + content: string, // The html generated from the body of each post + config: Object, // The config object defined above + nav: Array, // An array of Link objects +} +``` + +The `Link` object structure is as below + +``` +{ + level: number, // the depth level of the nav + active: boolean, // true if this item is currently selected + href: string, // url associated with the Link + title: string, // title specified for the Link + children: Array // List of child Links +} +``` + +This nav list is generated from the tree defined in the frontmatter of each index document under the `src` folder specified in the config. + +## Internals ### Document structure -Following is the structure of the document parsed and generated from Citadel +Following is the structure of the document parsed and generated from Citadel. ```js Document: