OrisonJS

Orison smoking pipe icon

A static site generator and server based upon lit-html

⇪

orison 1.2.4

bin/orison-generator.js

new OrisonGenerator(config)

Creates an OrisonGenerator that can be used to build a website based upon a specially formatted source directory.

Parameters
Name Type Description
config object Required configuration for the generator.  
config.rootPath string Required. Determines the root path of the source and build directories.  
config.generatePath string Optional. Defaults to "/". The sub path under the pages directory to generate the site from. Any pages outside of this subpath will not be deleted from the build directory or generated from the source directory. This allows partial builds of certain sub paths of the page hierarhcy.  
config.generateSlugs array Optional. Defaults to [ ]. A list of slugs to generate for list page types. List pages are a single source page that generates 0 or more pages in the build directory. If a list of slugs is provided these will be provided to the list source page so that the list page knows which pages to generate. This is helpful if you only want to generate pages for certain slugs instead of the list page generating every page.  
config.excludedPaths array Optional. Defaults to [ ]. A list of paths to exclude from the build. This is helpful for fine tuning what pages get rebuilt. If you want to rebuild the page at /src/pages/example/ but you want to exclude the subdirectories of the example directory they can be listed in this configuration.  
config.buildDir string Optional. Defaults to "docs". The name of the build directory where the built files will go. The build directory should exist under the root path.  
config.protectedFileNames array Optional. Defaults to [ "CNAME" ]. Protected file names that will not be deleted from the build directory. This defaults to "CNAME" which is a file that GitHub pages needs for hosting. This list can be updated based upon other hosting providers and setups.  
config.staticDirectory string Optional. Defaults to "static". The name of the static directory. This directory should exist under the source directory. It will be copied as is into the build directory.  
config.pagesDirectory string Optional. Defaults to "pages". The name of the pages directory. This directory should exist under the source directory. This is the directory that will be rendered into the build directory and forms the hierarchy of your site.  
config.srcDirectory string Optional. Defaults to "src". This is the source directory. The static directory, pages directory, and partials directory should all exist under this directory. The source directory should exist under the root path.  
config.layoutFileBasename string Optional. Defaults to "layout". The basename of the layouts created under the pages directory. Pages are inserted into the nearest layout within the pages hierarchy. As an example if "layout" is provided in this configuration then files named "layout.js" will be interpretted as layouts.  
config.dataFileBasename string Optional. Defaults to "data". The basename of the data files under the pages directory. The output of these data files are provided to pages and serve as contextual site metadata.  
config.fragmentName string Optional. Defaults to "fragment". The string to identify fragments with. Fragments are pages that get rendered without the layout. This allows for page content to be requested without the surrounding layout and helps support single page application style linking. If "fragment" is provided, then each page will get a corresponding file built with the format ".fragment.html" where the contents are the same as ".html" but without the layout applied and where is the basename of the corresponding page.  
config.loaders array Optional. Defaults to an empty array. Any objects put in this array should have a name property that is a string and a loader prop that is a function. Review the documentation on the details for implementing a loader.  
Returns

OrisonGenerator An OrisonGenerator based upon the provided configurations.

OrisonGenerator.build()

Build the static files for the website based upon the options provided in the constructor. This is essentially a three step process: (1) Delete the directories and files in the buildDir, (2) Copy the static files to the build directory, (3) Generate HTML files in the build directory based upon the page files (HTML, JS, MD) in the pages directory.

Returns

object Information about what was built.

bin/orison-server.js

new OrisonServer(config)

Creates an OrisonServer that can be used to serve a website based upon a specially formatted source directory.

Parameters
Name Type Description
config object Required configuration for the generator.  
config.rootPath string Required. Determines the root path of the source and build directories.  
config.buildDir string Optional. Defaults to "docs". The name of the build directory where the built files will go. The build directory should exist under the root path.  
config.srcDir string Optional. Defaults to "src". This is the source directory. The static directory, pages directory, and partials directory should all exist under this directory. The source directory should exist under the root path.  
config.pagesDir string Optional. Defaults to "pages". The name of the pages directory. This directory should exist under the source directory. This is the directory that will be rendered into the build directory and forms the hierarchy of your site.  
config.staticDir string Optional. Defaults to "static". The name of the static directory. This directory should exist under the source directory. It will be copied as is into the build directory.  
config.indexFileBasename string Optional. Defaults to "index". The base file name (without an extension) of the index files which are returned when a request comes through to a directory url instead of a specific file url.  
config.listFileBasename string Optional. Defaults to "list". The base file name (without an extension) of the list files. These files are single JS files used to generate a list of pages.  
config.layoutFileBasename string Optional. Defaults to "layout". The basename of the layouts created under the pages directory. Pages are inserted into the nearest layout within the pages hierarchy. As an example if "layout" is provided in this configuration then files named "layout.js" will be interpretted as layouts.  
config.dataFileBasename string Optional. Defaults to "data". The basename of the data files under the pages directory. The output of these data files are provided to pages and serve as contextual site metadata.  
config.loaderDir string Optional. Defaults to "loaders". The directory name under the src directory where the Orison loaders are defined. Review the Orison documentation for how to create a loader.  
config.fragmentName string Optional. Defaults to "fragment". The string to identify fragments with. Fragments are pages that get rendered without the layout. This allows for page content to be requested without the surrounding layout and helps support single page application style linking. If "fragment" is provided, then each page will get a corresponding file built with the format ".fragment.html" where the contents are the same as ".html" but without the layout applied and where is the basename of the corresponding page.  
config.page404 string Optional. Defaults to "404.html". The path to the 404 page. If you wish to use a JS file to generate the 404 page then you will need to update this extension. If you move the name of location of the 404 file this property needs updated.  
config.page500 string Optional. Defaults to "500.html". The path to the 500 page. If you wish to use a JS file to generate the 500 page then you will need to update this extension. If you move the name of location of the 500 file this property needs updated.  
config.stripHtml string Optional. Defaults to false. This determines if you want to strip the html url extension from urls.  
config.loaders array Optional. Defaults to an empty array. Any objects put in this array should have a name property that is a string and a loader prop that is a function. Review the documentation on the details for implementing a loader.  
config.port string Optional. Defaults to 3000. Change this to change the port that is used by the server.  
Returns

OrisonServer An OrisonServer based upon the provided configurations.

OrisonServer.start()
Returns

object Start serving the provided src directory at the provided port, rendering pages on the fly. Returns the express server that can be used for further configuration.

bin/orison-static-server.js

new OrisonStaticServer(config)

Creates an OrisonStaticServer that can serve the result of the OrisonGenerator. This can be used as a preview which more closely matche how the live site will behave than the OrisonServer. It requires that the OrisonGenerator as already been used to generate the static files.

Parameters
Name Type Description
config object Required configuration for the generator.  
config.rootPath string Required. Determines the root path of the source and build directories.  
config.dir string Optional. Defaults to 'docs'. This determines what directory the built files are in. This directories contents should be the output of the OrisonGenerator.  
config.port string Optional. Defaults to '3000'. Change this to change which port the static server should listen to.  
Returns

OrisonStaticServer An OrisonStaticServer based upon the provided configurations.

OrisonStaticServer.start()
Returns

object Start serving the provided build directory at the provided port. Returns the express server that can be used for further configuration.

bin/orison-directory.js

new OrisonDirectory(config)

A class representing a src pages directory. Provides easy to use accessor methods for retrieving contextual information about that given location under the src pages path.

Parameters
Name Type Description
config object Required. An object with configurations on how the source directory should be interpretted.  
config.path string Required. The path to the directory that this OrisonDirectory will represent. Should be relative to the pages directory.  
config.rootPath string Required. The absolute system level path to the root of the project.  
config.srcDirectory string Optional. The path to the source directory relative to the root directory.  
config.pagesDirectory string Optional. The path to the pages directory relative to the source directory.  
config.layoutFileBasename string Optional. The base name of the files to interpret as Orison layouts. These files should return a method which accepts a context object and returns a TemplateResult.  
config.dataFileBasename string Optional. The base name of the files to interpret as data files. These should be json.  
Returns

OrisonDirectory A new OrisonDirectory with the provided configurations.

OrisonDirectory.dataPath()
Returns

string The path to the Orison data json file in the current directory.

OrisonDirectory.isRoot()
Returns

boolean Whether or not this is the root directory of the src pages.

OrisonDirectory.layout()
Returns

function The layout to be used for pages within this directory. It will recursively search up the src pages path to find the closest layout.

OrisonDirectory.data()
Returns

object The JSON data associated to this src pages directory, coming from the data json file within this directory. The JSON object will always have a "orison" and "public" attribute.

OrisonDirectory.parent()
Returns

OrisonDirectory The OrisonDirectory object one level up the src pages path. This should not be called when this.isRoot this true.

OrisonDirectory.child()
Returns

OrisonDirectory The OrisonDirectory object of the given child directory.

OrisonDirectory.children()
Returns

Array An array of OrisonDirectory's representing the children of the current directory. They will be ordered based upon the value of the child.data.orison.order property of each child directory.

OrisonDirectory.parents()
Returns

Array An array of OrisonDirectory objects starting with this one and going up the directory hierarchy by calling the parent method until an OrisonDirectory object returns true for isRoot.