Universal Blog API

RuhohSpec v1.0 Directory Structure

The following outlines your blog's directory structure and includes helpful information and links to full documentation.

• . config.yml
• [Required] The config file is written in YAML and contains site-wide configuration options. config documentation
• . dash.html
• [Optional] dash.html provides a custom view of your dashboard, located at /dash in development mode. dash.html is optional; ruhoh will use its system level view if dash.html is not provided.
• . compiled
• [Optional] The compiled folder is the default location the Compiler will output pages into. When you run the Compiler, your fully rendered blog will output to this folder. compile documentation
• . media
  • . my-hockey-stick-graph.jpg
• [Optional] The media folder holds global static media assets such as images, videos, pdfs, downloads, etc. Theme-specific assets should NOT exist in this media folder, but rather in the theme's media folder. media documentation
• . pages
  • . index.md
  • . about.md
  • . random-folder
• [Optional] All files contained in the pages folder will be processed as pages. pages documentation
• . partials
  • . pages_list
  • . pages_collate
• [Optional] Partials are files which contain arbitrary layout code, usually HTML, that can be dynamically included into any page or layout.
• . plugins
  • . kramdown.rb
  • . tag_cloud.rb
• [Optional] Plugins extend and/or overload the base ruhoh functionality. There are 3 types of plugins: mustache helpers, converters, and compiler tasks. plugin documentation
• . posts
  • . open-source-is-good.md
  • . hello-world.md
  • . untitled-draft.md
• [Optional] All files contained in the posts folder will be processed as posts. posts documentation
• . site.yml
• [Optional] The site YAML file is used to specify site-wide data that can be used throughout your pages and layouts. A useful example is defining a navigation array that the templater can use to create your primary navigation bar.
• . themes
  • . twitter
    • . javascripts
    • . layouts
      • . default.html
      • . page.html
      • . post.html
    • . media
    • . partials
      • . posts_collate
    • . theme.yml
    • . stylesheets
    • . widgets
      • . WIDGET-NAME
        • . layouts
          • . WIDGET-NAME.html
          • . custom_layout.html
        • . stylesheets
          • . WIDGET-NAME.css
          • . custom_styles.css
  • . another-theme
• [Required] The themes folder holds all your themes. Themes are packaged into folders containing all layouts, partials, stylesheets, media, and javascripts necessary to style the website. theme documentation
• . widgets
  • . some_widget_name
    • . config.yml
    • . javascripts
      • . some_widget_name.js
    • . layouts
      • . some_widget_name.html
      • . alternative_view.html
• [Optional] Widgets define encapsulated mustache helpers to allow for customized HTML snippets that can optionally run javascripts and take in arbitrary configuration parameters. Client-side comments, analytics, and syntax highlighting are some automatically provided widgets. widget documentation

Interface Specification

Ruhoh parses your blog for data based on a standardized interface specification.

First, your blog is assumed to be wholly contained in one directory. This directory acts as the primary interface. Secondly, files contained in this directory have three vectors of specificity:

File Position

Files in specific folders necessarily define them as a certain data type. For example files in the "layouts" directory define the file as a layout and will error if not properly formatted as such.

File Name

Secondly, a file's name may define it's role. For example the main configuration file must be in a specific position (the root) and it must be named exactly config.yml.

File Contents

Lastly, a file's content must match it's implicit data-type as defined by its position and name. This means files in the posts folder must contain content formatted as a post, and files in the layouts folder must have a valid layout as its content.