Design

In the spirit of a blogging framework, I will intro the design choices behind Sculblog in a stream-of-thought prose piece.

Previously I was part of a clothing startup. Someday, I will write a blog post detaling how making clothing for half a year influenced my design taste, but, in one sentence: designing clothing accentuated a strong propensity towards minimalism in my design tastes in the way everything not neccassary had to be taken away to convey a core end-goal design and to accentuate the most important things on the limited space on the human body.

A year later I got into computers and started writing software. And during my software writing journey, I stumbled across so many connnections between clothing design and software design. You might thing the usage of the word "design" for both fields is merely an accident, but no, they were largely in the same domain! Not merely overlapping in semantic ways, in "oh I overlap these words from this field with these words from that field...," but in activating the same brain circutries before I even realized it was happening.

I believe there are so many good ideas, ideas across disciplines, formed by people's unique experiences, in people's minds that would impact the world if they got out... The invention of the laser was just a hobby and it led to hard drives... And that is why I have made this program, so people can focus on writing their ideas instead of website management, and thus change the world.

The Sculblog project started when I was making a personal website compiling lots of my previous work including software projects, prose pieces I had written, and visual design pieces. It all started growing in complexity rather quickly, and keeping consistency between multiple HTML files was next to impossible, so it made sense to me to take a bit of time to make a simple framework. PHP and SQLite was the combination that worked best. After the website went up, I found out that there was no website framework that was minimalistic, customizable, and easy-to-use, so, with a little bit more development, I created one! In keeping with my tendancies towards minimalism, I wrote Sculblog to render down to pure HTML. Sculblog is the only blogging framework that renders down to pure HTML while preserving layout consistency across pages.

There is great beauty in pure information. That's what computers do, they process information. Take our messy, imperfect world and turn it into an easily replicatable and preservable format. Tim Berners Lee... Aaron Swartz... So many of the greatest minds have put their work in pure HTML, a very pure syntactic format for sharing textual information. Aesthetically, pure HTML calls back to the old internet, when computers and the internet were being pioneered by madmen like John Perry Barlow. These visionaries made computers do the preservation, processing, and transferring of information, and I believe writing a program that will keep the focus of the internet on that will bring about the best and most transformative ideas for humanity.

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>