Full Orison API
This API is meant to be an internal API of the Orison implementation. For the public API designed for use by applications refer to the API page.
orison 1.3.5
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 " |
|
| 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 " |
|
| 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.
bin/markdown.js
mdFile(filePath)
Renders the markdown file at filePath, returning a lit-html template.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| filePath | string |
The markdown file to render. |
Returns
TemplateResult A lit-html template result with the rendered markdown file.
mdString(string)
Renders the markdown string, returning a lit-html template.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| string | string |
The markdown string to render. |
Returns
TemplateResult A lit-html template result with the renderd markdown string.
bin/orison-cache-loader.js
new OrisonCacheLoader(config)
A class which generates and maintains a list of Orison loaders. Refer to the Orison documentation on how to implement a lodaer function.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| config | object |
Required. An object with configurations on how the source directory should be interpretted. | |
| config.loaderPath | string |
Required. The absolute path to the directory containing the loader JS files. | |
| config.initialLoaders | array |
Required. An array contain objects each with a 'name' and 'loader' property. The name property should be a string and the loader property should be a function implementing the loader. Any programatically defined loaders. These will take precedence over any loaders found in JS files under the loaderPath. |
Returns
OrisonCacheLoader A new OrisonCacheLoader with the provided configurations.
bin/orison-path-maker.js
new OrisonPathMaker(rootPath, srcDir, pagesDir)
A class for generating OrisonPath objects.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| rootPath | object |
Required. The absolute rooth path in the file system where the src directory is. | |
| srcDir | object |
Required. The name of the src directory. | |
| pagesDir | object |
Required. The name of the pages directory. |
Returns
OrisonCacheLoader A new OrisonCacheLoader with the provided configurations.
OrisonPathMaker.create()
Returns
object An OrisonPath object based upon the configuration provided in the constructor and the relative src path provided to this method.
OrisonPathMaker.pagesPath()
Returns
string the absolute file system path to the pages directory.
OrisonPathMaker.srcPath()
Returns
string the absolute file system path to the src directory.
bin/orison-path.js
new OrisonPath(relPath, pathMaker)
This class encapsulates logic for generating paths and determining information about a relative src path.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| relPath | object |
Required. The relative path from the src directory. | |
| pathMaker | object |
Required. The OrisonPathMaker object which contains the information needed for calculating absolute paths. |
Returns
OrisonCacheLoader A new OrisonCacheLoader with the provided configurations.
OrisonPath.full()
Returns
string The absolute path to the relative path provided in the constructor.
OrisonPath.rel()
Returns
string The relative path as provided in the constructor.
OrisonPath.exists()
Returns
string Whether a file or directory exists at the provided path.
OrisonPath.isDirectory()
Returns
string Whether the item specified by the rel path is a directory.
OrisonPath.stat()
Returns
string The fs.statSync results for the provided rel path.