Skip to content

Latest commit

 

History

History
122 lines (89 loc) · 8.73 KB

README.md

File metadata and controls

122 lines (89 loc) · 8.73 KB
Raw

Creating Arise Pages

This documentation page will explain how Arise websites are structured, how to create new pages, and the options that are available when configuring a new page.

Site Architecture Overview

All pages in Arise have a common modular structure. Each page is made up of a folder with an index.md at the root of the page. Thumbnails, images, and other page assets should be stored in the same folder as the page index.md file. The basic structure of every page in Arise can be visualised like this:

    .
    ├── pagename/
    │   ├── index.md
    │   ├── thumbnail.png
    │   └── [other assets]
    └── ...

When Arise builds your site, it traverses the folder structure of the entire site and builds everything with the above structure in mind.

For large folders full of pages, Arise also supports the creation of dynamically generated index pages. You can tell Arise to create an index page at a given folder by using the toc setting (see: Optional Settings) in your index folder's index.md.

The structure of an Arise website making use of indices should look something like this:

    .
    ├── index1/
    │   ├── index.md
    │   ├── page1/..
    │   └── page2/..
    │
    ├── index2/
    │   ├── index.md                                   
    │   ├── page1/..                                                                   
    │   └── page2/..  
    └── ...

Creating New Pages

To create a new page, simply create a folder and make an index.md file with an Arise metadata header at the very top of the file. A standard Arise metadata header looks like this:

<!-- BEGIN ARISE ------------------------------
Title:: "My Cool Page"

Author:: "Johnny Silverhand"
Description:: "Write a thrilling description here"
Language:: "en"
Thumbnail:: "thumbnail.png"
Published Date:: "2077-05-12"
Modified Date:: "2077-05-12"

toc:: "false"
process_markdown:: "true"
content_header:: "true"
---- END ARISE \\ DO NOT MODIFY THIS LINE ---->

The Arise metadata header is broken up into three sections Critical settings, Standard settings, and Optional settings. The setting variable names are case sensitive.

Critical Settings

If critical settings are not included or are left blank your page will not build. There is currently only one critical setting:

  • Title: This is the human-readable title of your web page. It cannot be left blank or your page will not build.

Standard Settings

Standard settings must be present in your page header, but they can optionally be left blank. However, it is not recommended to leave them blank because your page will be missing SEO data if these settings are not populated.

  • Author: Who wrote this page
  • Description: A brief human-readable description of your page. This will be what appears in the subtext of search engine results or social media that supports rich embeds, so you are advised (but not required) to keep this field under 120 characters in length.
  • Language: The ISO 639-1 language code for the language your page is written in.
  • Thumbnail: The filename of your thumbnail image. The thumbnail image must be in the same folder as your index.md for your page.
  • Published Date: The ISO-8601 short date (aka: YYYY-MM-DD) for when your page was originally published to your site.
  • Modified Date: The ISO-8601 short date (aka: YYYY-MM-DD) for when your page was last modified.

Optional Settings

Optional settings can be omitted entirely from your header. These settings contain advanced options for special functionality within Arise. If you choose to omit one of these options, Arise will build your page with the default setting for any omitted optional setting. Optional page settings that are available include:

  • content_header: (Default: true) Arise has a special build file config/content_header.html with content to be appended to every page immediately after the opening <body> tag. However, for some special pages on your website, you may want to format the body of your page in a completely unique way that omits your standard site elements within the <body>. If you set content_header to "false", the content header (but not SEO header) will be omitted from your special page so that you can format the body individually for that page.
    • By default, the only thing included in the content header is a tag to display the post date and author of any given post. You can always add more or change the default content header to your liking if you have other standard content you'd like included in the body of your page!
  • process_markdown: (Default: true) Arise is designed to build pages written in Markdown. However, let's say you have a page that is already written in HTML. When you set process_markdown to "false", Arise will skip the step of converting Markdown into HTML and just pass the raw contents of your index.md as the body of your page.
    • This setting is particularly useful if you are porting content from another website that already has the body of your content in HTML format and you don't want any additional processing beyond the addition of a header+footer to be done to it.
  • toc: (Default: false) This is a special setting that instructs Arise that the folder containing this index.md isn't actually a normal page, but rather a folder containing other pages that you'd like a traversable index/TOC built for. If you set toc to "true", Arise will look through all the folders contained in the current folder, grab their metadata if they are Arise-formatted pages, and generate a pretty index for you.
    • If this setting is enabled, Arise will ignore all content present after the Arise metadata header and create an index/TOC page instead.
  • rss_hide: (Default: false) When set to "true", this setting hides your page from the RSS feed. This is useful for meta pages (privacy policy, contact, etc) that you don't want to send to the feeds for your RSS readers.
    • Note that dynamically generated TOC pages are automatically hidden from your RSS feed, so you do not need to manually add this setting for those pages.

Page Themes

All pages in Arise are built by concatenating the following files in the following order:

If you want to change the style or overall layout of your website, you need to edit the /config/header.html file for your website.

By default, the stylesheet used by /config/header.html is /config/main.css.

The Arise header supports the following dynamic metadata tags, which will be populated with info from the page being built at build time:

  • {{base_url}} - The base url for your website, in the format of https://example.com
  • {{global_name}} - The human-readable global name of your website
  • {{title}} - The title of the page being built
  • {{author}} - The author of the page being built
  • {{description}} - The human-readable description of the page being built
  • {{language}} - The ISO 639-1 language code for the language your page is written in.
  • {{thumbnail}} - The filename of your thumbnail image.
  • {{published_date}} - The ISO-8601 short date (aka: YYYY-MM-DD) for when your page was originally published to your site.
  • {{modified_date}} - The ISO-8601 short date (aka: YYYY-MM-DD) for when your page was last modified.

Note that Arise automatically checks metadata strings for XML-unsafe characters and replaces them with XML escape codes at runtime. This ensures that you don't accidentally break your sitemap or RSS feed by having quotes or whatever in your page metadata.

Caveats & Gotchas

There are some caveats to how this data is processed that you should be mindful of.

  • Arise specifically looks for files titled index.md for its build process. Do yourself a favour and don't name files index.md if you don't want Arise to include them.
  • /config is a specially directory reserved for site templates and live sitewide assets. Arise will not build pages in this folder or its subfolders.