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 " |
|
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
.