<<<Back to Coding

Sculblog

Design

Sculblog is written in Python and built on top of pre-existing technologies - Debian, Apache, HTML, CSS, PHP, SQLite, browsers. These technologies are established, reliable, and easily customizable, perfect for building a lightweight blogging framework on top of.

Versioning

Sculblog 0.1.6 is for an Apache server running on Debian. Future versions will support Nginx

Installation

• On a fresh Debian instance, run install.sh, or run source curl http://diegocabello.com/sculblog/install.sh.
• Create a Python venv in your home directory using python -m venv sculblog
• Run source sculblog/bin/activate to activate the venv
• Run pip install sculblog

Features

Root Directory Structure

• All posts are written in Markdown or HTML, are converted to html if neccassary, and put in the database.
• The files in the server root directory /var/www/html/ 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
• The database is stored in the 'database' folder in the server directory.

Compared to alternatives like Hugo, this configuration is much simpler and doesn't require learning a whole new scripting language.

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

• 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;

Schema

Sculblog posts have a required schema so that Sculblog posts can be cross-hosted between different websites. All these fields are TEXT in SQLite.

Required Schema

• file_name - this is what the url points to. It is the name of the php file and the markdown file in the content directory. Must contain only lowercase letters and single hyphens. Cannot start or end with a hyphen
  • Regex pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
  • Note: the value for file_name uses hyphens for spaces; column names use underscores for spaces. This is to prevent any ambiguation between the two use cases
• header - this is the text with capitalization and spaces that gets rendered in the header element on the page or the listing.
  • Not called 'title' to avoid ambiguation between it and file_name
• text - this is the HTML stored in the database that gets rendered in the php.

Reccomended Schema

• preview_text - the text all put into one p eleement, with optional stylistic highliting for headers, links, and more. Shows up in the listings. Automatically formatted from text
• author - the author
• date - the date
  • recommended format is DD MMM YYYY (Ex. 03 Dec 2024) to avoid confusion between American and international date formats
• tags - seperated by commas. case insensitive, spaces allowed around tags
  • Regex pattern: ^([\w\s-]+\s*,\s*)*[\w\s-]+$
• hide - anything in this column that is not empty or whitespace will hide the post

In the spirit of extensability, anything else goes.

Commands

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: sculblog process <post_name>