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

• On a fresh Debian instance, run install.sh, or run curl https://diegocabello.com/sculblog/install.sh | bash.

There are two ways to install the Sculblog Python package.

1. Create a Python venv in your home directory using python -m venv sculblog; run source sculblog/bin/activate to install and each following time you start a session; and run pip install sculblog to install in the venv
2. Install it with pip install sculblog --break-system-packages. This way is the suggested way

Root Directory Structure

• All posts are written in Markdown or HTML, are converted to HTML if necessary, 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 in the server root directory. 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 corresponding 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 Definitions

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

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

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 ambiguity 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 ambiguity between it and file_name
• text - this is the HTML stored in the database that gets rendered in the php.

Recommended Schema

• preview_text - the text all put into one p element, 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 - separated 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 extensibility, anything else goes.

All commands follow the schema `sculblog

• The file_name must have the file extension.

Post Creation

These commands are used to convert markdown content into HTML.

• preview is used to see what a post will look like in the browser, without increasing the draft number. It can be accessed by the url query string ?draft=0.
• draft command increments a new draft for versioning history. Each draft can be accessed by the url query string ?draft=.
• update is used to change the content on the latest draft and the preview. The intended purpose is for minor corrections without creating a new version.

These commmands also have some side effects.

• It formats preview HTML, which 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 default date format is DD-MMM-YYYY to avoid confusion between American and European date formats.

Hide & Unhide

The hide and unhide commands determine whether a post doesn’t or does show up on the listings, respectively.

Date & Header

The date and header commands are used to change the string value of those attributes for a post.