faggot Documentation

Sculblog

<<<Back to Sculblog

Documentation

Date: 16 Nov 2024

Tags:

Words: 996

Features

Root Directory Structure

  • Sculblog serves everything from a 'public' folder in the server directory.
  • All posts are written in Markdown in the 'content' folder in the server directory, are converted to html from the binary, and put in the database.
  • The files in the 'public' directory are linked to templates stored in the 'resources' folder in the server directory.
    • The templates connect to the database.
    • Templates are written in php by default but can be configured to support any number of other languages.
  • The database is stored in the 'database' folder in the server directory.

These choices for the directories were made for access control so only the 'public' folder is available on the internet, and because editing server configuration to hide all the other folders is a complete pain.

Optimized Content Serving

  1. Update once, update everywhere
    • including post previews and tags in multiple places such as the subdirectory index page and the website home page
  2. More robust content organization and retrieval
    • Tagging and filtering systems expand to multiple categories with no redundancy
    • Utilization of HTTP query parameters for filtering eliminates the need for tag-specific directories
  3. More efficient content serving, dynamically rendered content
    • Database-driven rendering for on-demand content assembly
    • Efficient queries enable complex pagination and retrieval logic
    • Eliminates full static-site rebuilds, optimizing update speed

Default Website Structure

  • Sculblog has more than one "subdirectory" (or category, but we will refer to it as "subdirectory" here) in the 'public' folder. Each subdirectory:
    • Gets a link on the header
    • Has an 'index.php' page that connects to a listing php file in the 'resources' folder that shows listings of all the posts for its subdirectory. The index file allows for blurbs describing the category before the listings.
    • Has a coresponding table in the database that by default has the same name as it
    • Has its posts stored in unique one-line php files that all link to a 'chain.php' file
  • The listing file...
    • Shows page titles that link to the page file for each post
    • Has the attributes for each post. The attributes are configured in an 'attributes' file in the 'resources' folder.
    • Shows a configurable three-line preview of the post content
  • Each post...
    • Will have its content stored in a table that by default will have the same name as the subdirectory
    • Is accessed through the internet in a unique one-line php file in its subdirectory/category. This is chosen against querying the database with http parameters for aesthetic simplicity in the url.
    • Its unique php file links to the 'chain' php file in its subdirectory
  • Each 'chain.php' file...
    • Configures the post template and attributes template in the 'resources' folder to refer to. This allows for quick swapping between templates for all posts at once. These templates then query to the database
    • Configures the table name in the database to query for. This gets passed to the templates which query the database. This configuration is chosen against getting the folder name in PHP because of overhead. It also allows the option to make the names of the database table and the subdirectory to be different (but this is not recommended).
    • The 'chain' file design means that there is no possibility for a hidden configuration error in only one file. If something is wrong, YOU WILL KNOW.
    • This is chosen over doing a grep/sed expression because errors can still slip in if one or more files are manually edited.

Post Organization

Post are sorted:

  • First by the custom order in the "date_order" column in the table in decreasing order - showing the newest ones first
  • Then by the unique auto-incrementing identifier in decreasing order - showing the newest ones first

Component Defenitions

This notation is provided in Extended Backus-Naur Form.1

  • Page = Header, [BackLink], Content, Footer;
  • Header = Title, Navigation, Categories;
  • Content = Article | Listing;
  • Article = Title, Attribues, Body, Thoughts;
  • Attributes = Date, Tags, WordCount;
  • Listing = {PostPreview};
  • PostPreview = Title, Attribues, TextPreview;

Short-Form Thoughts

Sculblog also features support for short-form text content called "thoughts". These thoughts also are categorized for each of the subdirectories, can appear at the bottom of each subdirectory page, and each long-form post. The idea behind this is to capture one-off ideas or phrases that could become highly salient. It also is to become a sort of self-hosted one-person twitter. Sculblog thoughts can be configured to display tweets from a Twitter account.

Installation

To install Sculblog, first install Rust on your system. Then, run cargo install sculblog.

Commands

Create

The create command in sculblog can be used to create two types of things: a category and a post.

Category

Creating a category in sculblog:

  • Creates the directory in the public directory
  • Creates an index.php file in that folder that by default links to the listing.php file in the resources folder
  • Creates a chain.php file in that folder that by default links to the post-template.php file in the resources folder and defines which attributes set to link to - by default it is post-attrs.php in the resources folder
  • Creates a table in the database with the same name

Usage: create category <category_name>

Post

Creating a post in sculblog:

  • Requires a post name. It is encouraged to keep this name concise
  • Requires a category to be put in. If no category is specified it will be put in the default category blog
  • Requires a header, which is the display title, which can include spaces or more elaboration, different from the file name
  • Creates a php file named for the post name that links to the chain.php file in the folder
  • Creates an entry in the database for that post name

Usage: create post <category_name> <post_name> <header>

Process

The process command in sculblog is used to convert markdown content into HTML and preview HTML.

  • It requires the category name the post is in
  • The preview HTML is for the listing previews, so the reader can see some content without clicking on the page.
  • It updates the 'date' column in the database to whatever the current date is. The preferred date format is DD-MMM-YYYY to avoid confusion between American and European date formats.

Usage: process <category_name> <post_name>

  1. As defined in ISO/IEC 14977 ↩

Thoughts

The internet... just as the founding fathers intended it!

<<<Back to Sculblog

Home