How it works

Spirit behind SBSharp is to start from the .adoc you can write, load it in an consolidated model then let your view drive the rendering of the website.

Configuration

SBSharpConfiguration

Configuration of the Maven local cache and remote repositor(ies).

Build: Build configuration. See BuildConfiguration section.
Input: Input configuration. See InputConfiguration section.
Output: Output configuration. See OutputConfiguration section.
PostProcessing (array): Post-processing configuration, often enables to work on the generated content to optimize it. Common examples are regenerating the index to make it precomputed for the runtime - depends the js query libraring, or pre-render the code snippets with highlighting - depends the library too. See PostProcessingConfiguration section.
Serve: Serve specific configuration - serve command only. See ServeConfiguration section.
Watch: Watch specific configuration - serveand watch commands only. See WatchConfiguration section.

BuildConfiguration

Build specific configuration.

RazorLocalCache: If not empty, where to cache compiled templates for faster launch.

Default value:.

Environment variable:SBSHARP__BUILD__RAZORLOCALCACHE.

Command line:--sbsharp:Build:RazorLocalCache=<value>.

InputConfiguration

Site input configuration - page content, views, assets, ....

Assets: Assets files globbing (includes/excludes). Often used for pictures and resources. See GlobbingConfiguration section.
AssetsLocation: Assets directory, can be absolute or relative to site Location.

Default value:_assets.

Environment variable:SBSHARP__INPUT__ASSETSLOCATION.

Command line:--sbsharp:Input:AssetsLocation=<value>.
Location: Site source base directory.

Default value:..

Environment variable:SBSHARP__INPUT__LOCATION.

Command line:--sbsharp:Input:Location=<value>.
RemoteView: if not false, the views (ending in View configuration directory) will be downloaded. See RemoteViewConfiguration section.
Sources: Site source (pages) file globbing (includes/excludes). See GlobbingConfiguration section.
View: View directory, can be absolute or relative to site Location.

Default value:_views.

Environment variable:SBSHARP__INPUT__VIEW.

Command line:--sbsharp:Input:View=<value>.
VirtualPages (array): Virtual pages definitions. See PageDefinition section.

GlobbingConfiguration

How to filter files in a directory (includes/excludes).

Excludes: Excluded files (glob patterns relative to input location).

Default value:**/_site/**.

Environment variable:SBSHARP__INPUT__ASSETS__EXCLUDES__<index>.

Command line:--sbsharp:Input:Assets:Excludes:<index>=<value>.
Includes: Included files (glob patterns relative to input location).

Default value:**/*.css, **/*.js, **/*.jpg, **/*.png, **/*.gif.

Environment variable:SBSHARP__INPUT__ASSETS__INCLUDES__<index>.

Command line:--sbsharp:Input:Assets:Includes:<index>=<value>.

RemoteViewConfiguration

Remote view (zip) download configuration.

PageDefinition

Defines a page template - does not need a .adoc file. Often used for navigation pages. It is primarly intended for pagination since for other pages you can use a .adoc with a specific view attribute.

Attributes: Page attributes - just forwarded to the view. Note that in the view model you can also query paginationTotalPages attribute and paginationAttributeValue (if relevant).

Default value:.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__ATTRIBUTES__<key>.

Command line:--sbsharp:Input:VirtualPages:$index:Attributes:<key>=<value>.
CriteriaAttribute: The attribute of the physical pages to use to paginate - page is ignored when not with this attribute.

Default value:category.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__CRITERIAATTRIBUTE.

Command line:--sbsharp:Input:VirtualPages:$index:CriteriaAttribute=<value>.
OrderByAttribute: Attribute to order pages by - if missing, empty is used.

Default value:published-on.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__ORDERBYATTRIBUTE.

Command line:--sbsharp:Input:VirtualPages:$index:OrderByAttribute=<value>.
PageSize: When view is Paginated, the page size to use.

Default value:10.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__PAGESIZE.

Command line:--sbsharp:Input:VirtualPages:$index:PageSize=<value>.
Paginated: Is it a paginated kind of page, ie PageSize will be used to render it.

Default value:False.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__PAGINATED.

Command line:--sbsharp:Input:VirtualPages:$index:Paginated=<value>.
PerValue: If True and paginated, the rendering generates the index per attribute value (think category) else it is global whatever the value is - but it ensures it exists. Take care that values are split on commas (tags, categories cases) so ensure to use an attribute respecting this constraint.

Default value:True.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__PERVALUE.

Command line:--sbsharp:Input:VirtualPages:$index:PerValue=<value>.
ReverseOrderBy: Should sorting be reversed.

Default value:True.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__REVERSEORDERBY.

Command line:--sbsharp:Input:VirtualPages:$index:ReverseOrderBy=<value>.
Slug: Slug to use - filename without extension, it must be set since will be the base of the output location of the generated page. If - and only if - paginated you can use {Page} to represent the page number (starting from 1) and {Value} representing the attribute value for rendered pages. If you want to use path separators, ensure to use /. Ensure to NOT start by a slash or the location will be considered absolute.

Default value:.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__SLUG.

Command line:--sbsharp:Input:VirtualPages:$index:Slug=<value>.
Title: Page title, similarly to the slug you can use page and value variables.

Default value:.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__TITLE.

Command line:--sbsharp:Input:VirtualPages:$index:Title=<value>.
View: View used to render the page(s).

Default value:default.

Environment variable:SBSHARP__INPUT__VIRTUALPAGES__$INDEX__VIEW.

Command line:--sbsharp:Input:VirtualPages:$index:View=<value>.

OutputConfiguration

Site output rendering configuration.

Attributes: Asciidoc (global) attributes to use for the rendering.

Default value:partialsdir=_partials, imagesdir=_images.

Environment variable:SBSHARP__OUTPUT__ATTRIBUTES__<key>.

Command line:--sbsharp:Output:Attributes:<key>=<value>.
Index: Should user pages be indexed in a JSON document for a client side search (flexsearch friendly). See IndexationConfiguration section.
Location: Site output base directory.

Default value:_site.

Environment variable:SBSHARP__OUTPUT__LOCATION.

Command line:--sbsharp:Output:Location=<value>.
NotBeforeToday: If True, posts where the date set in the attribute published-on is before today will be ignored. Expected format: yyyyMMdd. If no date is found the post is considered published - but it is not expected.

Default value:True.

Environment variable:SBSHARP__OUTPUT__NOTBEFORETODAY.

Command line:--sbsharp:Output:NotBeforeToday=<value>.
Rss: Should and how the RSS feed be generated. See RssConfiguration section.
UseBootstrap: If True, part of asciidoc rendering is replaced by native bootstrap (5) HTML.The most visible is to replace the standard table based adminiton by bootstrap alerts.

Default value:True.

Environment variable:SBSHARP__OUTPUT__USEBOOTSTRAP.

Command line:--sbsharp:Output:UseBootstrap=<value>.

IndexationConfiguration

JSON indexation output configuration.

Enabled: Should user pages be indexed in a JSON document. Using index-skip attribute you can disable a page indexation.

Default value:True.

Environment variable:SBSHARP__OUTPUT__INDEX__ENABLED.

Command line:--sbsharp:Output:Index:Enabled=<value>.
IndexedAttributes: List of indexed data, they are all read in page attributes except index-title which uses the document title - if the attribute value is not false which disables the virtual attribute and index-body which is the document in html and index-publishedon which is the publication date in ISO8601 format. For convenience, index-gravatar computes the author gravatar URL. Note that index-description can be replaced by description if it does not exist. Finally, on client side - in the JSON - the index- prefix is always stripped. A common default value would be index-title,index-description,index-body,index-publishedon for example to enable to render a search result with some minimal information and search based on the body (totally optional, you can even think to a custom keyword attribute). This is what is used when the value is not set.

Environment variable:SBSHARP__OUTPUT__INDEX__INDEXEDATTRIBUTES__<index>.

Command line:--sbsharp:Output:Index:IndexedAttributes:<index>=<value>.
Location: Where to output the index if enabled (absolute or relative to output location).

Default value:index.json.

Environment variable:SBSHARP__OUTPUT__INDEX__LOCATION.

Command line:--sbsharp:Output:Index:Location=<value>.

RssConfiguration

RSS feed output configuration.

Copyright: RSS feed copyright, take care it is the XML value directly without any escaping.

Default value:Built with SBSharp.

Environment variable:SBSHARP__OUTPUT__RSS__COPYRIGHT.

Command line:--sbsharp:Output:Rss:Copyright=<value>.
Description: RSS feed description, take care it is the XML value directly without any escaping.

Default value:Blog.

Environment variable:SBSHARP__OUTPUT__RSS__DESCRIPTION.

Command line:--sbsharp:Output:Rss:Description=<value>.
Enabled: Should RSS feed be generated. Note that when enables the attributes rss-skip can be used to ignore a page and rss-description/description to set a RSS page description.

Default value:True.

Environment variable:SBSHARP__OUTPUT__RSS__ENABLED.

Command line:--sbsharp:Output:Rss:Enabled=<value>.
Link: RSS feed link, take care it is the XML value directly without any escaping.

Default value:http://localhost:4200.

Environment variable:SBSHARP__OUTPUT__RSS__LINK.

Command line:--sbsharp:Output:Rss:Link=<value>.
Location: Where to output the RSS feed if enabled (absolute or relative to output location).

Default value:rss.xml.

Environment variable:SBSHARP__OUTPUT__RSS__LOCATION.

Command line:--sbsharp:Output:Rss:Location=<value>.
Title: RSS feed title, take care it is the XML value directly without any escaping.

Default value:Blog.

Environment variable:SBSHARP__OUTPUT__RSS__TITLE.

Command line:--sbsharp:Output:Rss:Title=<value>.
Ttl: RSS feed ttl.

Default value:1800.

Environment variable:SBSHARP__OUTPUT__RSS__TTL.

Command line:--sbsharp:Output:Rss:Ttl=<value>.

PostProcessingConfiguration

Tasks ran after the generation.

Command: The command to execute.

Default value:.

Environment variable:SBSHARP__POSTPROCESSING__$INDEX__COMMAND__<index>.

Command line:--sbsharp:PostProcessing:$index:Command:<index>=<value>.
Environment: The environment to execute the command to, every entry is formatted as ENV_VAR_NAME=env var value.

Default value:.

Environment variable:SBSHARP__POSTPROCESSING__$INDEX__ENVIRONMENT__<index>.

Command line:--sbsharp:PostProcessing:$index:Environment:<index>=<value>.
LogMessage: An optional log message to print when executing the command, empty values will ignore this feature.

Default value:.

Environment variable:SBSHARP__POSTPROCESSING__$INDEX__LOGMESSAGE.

Command line:--sbsharp:PostProcessing:$index:LogMessage=<value>.
WorkDir: The directory to execute the command from, empty means the Input.Location value, if not absolute it is relative to the Input.Location value.

Default value:.

Environment variable:SBSHARP__POSTPROCESSING__$INDEX__WORKDIR.

Command line:--sbsharp:PostProcessing:$index:WorkDir=<value>.

ServeConfiguration

Serve command specific configuration.

Urls: Urls to serve from.

Default value:http://localhost:4200.

Environment variable:SBSHARP__SERVE__URLS__<index>.

Command line:--sbsharp:Serve:Urls:<index>=<value>.
WatchEnabled: Should watch mode be enabled for serve command, ie the site rebuilt on detected changes.

Default value:True.

Environment variable:SBSHARP__SERVE__WATCHENABLED.

Command line:--sbsharp:Serve:WatchEnabled=<value>.

WatchConfiguration

Watch and serve command file system watching specific configuration.

Debouncing: When enabled, how long (in milliseconds) to await before rebuilding the website - to avoid to keep rebuilding it when typing.

Default value:250.

Environment variable:SBSHARP__WATCH__DEBOUNCING.

Command line:--sbsharp:Watch:Debouncing=<value>.

Your first content

The .adoc source in "input location" - see configuration - is loaded in a model then provided to the configured view.

Tip

if no view is configured, then defaultone - default.cshtml in view directory - is used.

= My Title (1)
:view: my-view (2)

My content in asciidoc. (3)

The page title,
The view to use for the rendering,
The page content.

This model is then converted in such a model - represented as JSON for simplicity:

{
    "Document": { (1)
        "Header": {
            "Title": "...",
            "Author": {"Name":"...","Mail":"..."},
            "Revision": {"Number":"...","Date":"...","RevMark":"..."},
            "Attributes": {
                "Key1": "Value1",
                ...
            }
        },
        "Body": {...}
    },
    "Body": () => "...content...", (2)
    "Slug": "...", (3)
    "GlobalAttributes": { (4)
        "Key1": "Value1",
        ...
    },
    "GlobalContext": { (5)
        "Pages": [ {...} ]
    }
}

The raw asciidoc model (not rendered),
The HTML body of the document (rendered as HTML),
The document slug (either from the asciidoc file file name without the extension or from the :slug: attribute),
Global attributes set for the rendering in the configuration (can be used as default of the header attributes - specific attributes),
Access to the rendering context - which enables to render more than just the current page like closest other page for example - or a reference to it at least.

The view attribute is optional and defaults to default if not set, it is then used to resolve the RazorLight (think Razor) view in the view directory (see configuration). The view is compiled and rendered passing this model as parameter - accessible with Model implicit variable.

For example, this my-view.cshtml file in view directory will render previous document:

<html>
<head>
    <title>@Model.Document.Header.Title</title>
</head>
<body>
    <div class="landing container pt-4">
        @Raw(Model.Body())
    </div>
</body>
</html>

Tip

Raw function enables to inject a pre-rendered HTML without any escaping - as Html.Raw in plain Razor, this is a RazorLight feature.

Virtual pages

Virtual pages are a way to generate pagination based pages. It is mainly useful for index kind of pages.

It can be global (filtered by the presence of an attribute - ensure the page is a post for example) or per attribute value (author name).

In this last case, the attribute value is considered comma-separated (for example John, Doe will handle two values, John and Doe).

Tip

create a custom attribute if you need something more precise where there is no comma.

See the configuration section for more details about how to enable that.

Important

it is super important to set a slug and a title to virtual pages since they will generally be used by your views to make the rendering - often the layout - specific.