Cleaning Things Up & Future PHPetite Updates

It has been quite a long time since I've reviewed or updated this little project of mine. Since it's release, I've created another minimal blogging system (based on bash this time) called Shinobi and converted my personal website to use that instead.

But I still love this single file blogging concept. So, I thought it was time for some basic cleanup. That "cleanup" slowly turned into a TODO list of sorts and now there are extra features I plan to add.

The Cleanup

* I first started by including the specific $_SERVER['DOCUMENT_ROOT']. parameter in the main PHP includes. I noticed when pulling the project in a "fresh" instance that the build failed without this setup. Sorry for anyone who may have ran into this issue previously!

* The default build script has been moved into a proper makefile. Now, generating the website only requires you to run make from the main directory. Running make serve builds the website and also runs a local server for testing at localhost:8000. Nothing groundbreaking but pretty helpful.

* The original dark mode CSS styling has been removed in favor of using the browser supported color scheme meta tag.

* Post dates are now listed at the top of each blog article (see above for reference)

What's to Come

I keep a running list of features I plan to implement (in no particular order) on the main about section. Feel free to open an issue on the official sourcehut todo if you have other features and suggestions. Don't be shy!

Follow Along

Rolling out any new updates for this project will take time. I'm in no real rush and I do have other projects that require my attention. That said, if you wish to stay up-to-date, I recommend following along via the official RSS feed.

Thanks for reading and happy single-file blogging!

-- Brad

Converting Custom Fonts to Base64 Strings

There are currently no plans to automatically convert custom fonts to base64 strings within the project itself - but it is very easy to do so manually for Mac/Linux users.

Simply open a terminal window and navigate to where your custom font file is located. The enter the following command (replacing the font extension name with your appropriate file name):

base64 your-custom-font.woff2 > font-base64.txt

Then in your style.css file, add the custom font as you normally would via the @font-face property but this time utilizing base64:

@font-face {
    font-family: 'FontName;
    src: url(data:font/woff2;base64,[BASE64 CODE]) format('woff2');
}

Things to Keep in Mind

Remember that by using base64 strings you are significantly increasing the overall size of your single file project. This should be used for extreme use cases where a single file website/blog isn't allowed access to 3rd party URLs or extra files on the root server. Hence why by default it isn't include in the PHPetite project itself.

Live Example

You can check out the ThriftyName project (built on PHPetite) to see base64 custom fonts in use.

Disable Image to Base64 Conversion

Some users¹ may wish to host their imagery and media via a 3rd party source or simply want to avoid the heavy weight added with using base64 strings (~133%+ in size).

To disable this feature, open your _phpetite/_config.php file and change the images_to_base64 variable to false.

// Activate or disable images to base64 strings
$images_to_base64 = false;

Automatic RSS

PHPetite ships with a very basic and crude auto-generated RSS feed. When you run the project's build script:

bash build.sh

it not only generates the single HTML blog file, but also creates an atom.xml file in the root directory. Simply share this with your followers or link it somewhere on your site itself (eg. yourdomain.com/atom.xml).

You can view this site's RSS feed here:

https://phpetite.org/atom.xml

The Benefits of a Single File Blog

Rendering your blog or website as a single file using PHPetite is pretty fantastic. It gives you the freedom to easily share, host or edit your site's content on almost any hosting provider.

Since the entire blog's content is generated inline on build, you don't need to fiddle around with external CSS and JS files. There is also no need to worry about broken img sources since PHPetite converts all images into proper base64 strings.

Using this website as an example: this blog weighs in at ~21KB¹.

That is incredibly tiny in terms of website size. Some sections on other web pages are larger than that!

The portability of having a single HTML file as your blog is quite liberating. Though it should be noted, if your blog consists of high resolutions imagery or includes massive amounts of content, a single file might be a little impractical for you.

Hosting for Newcomers

I suggest using Netlify Drop if this is your first time setting up a hosting environment or you don't consider yourself too tech-savvy. Once you have your rendered index.html file, simply drag-and-drop the file into Netlify Drop - that's it!

From there you can always setup a permanent subdomain or use your own custom domain.

Local Development

Simply follow the instructions found on the Generating This Blog page and you'll be running a local version of your site in seconds.

Converting from Jekyll

This walkthrough is still being tweaked and optimized. Check back soon for the final version!

Markdown examples

On top of plain Markdown, Markdown Extra adds support for footnotes, abbreviations, definition lists, tables, class and id attributes, fenced code blocks, and Markdown inside HTML blocks.

Additionally, images are properly enclosed in figure elements (with optional figcaption), and the loading="lazy" attribute is added.

This is bold, italic, this is an internal link, this is not code, press alt.

This text is in a blockquote.

This is a level 2 heading

This is a level 3 heading

• This
• is
• a list

0. This
1. is
2. an
3. ordered list

This is
    preformatted
  text.

This sentence has a footnote.¹

Structuring Blog Posts

Blog posts should be placed into the /content directory and be named based only on their post date. See an example here:

2048-01-01.md

PHPetite will create a target by appending the page title inside the article to the file's date name. So a markdown file with the following content:

# Bladerunner Rocks

Bladerunner is amazing because blah blah blah...

will render out the target link as:

example.com/#2048-01-01-bladerunner-rocks

Requirements

1. PHP 7.3 or higher
2. If using Linux, you will require the following packages in order to convert your images to base64 encoding:
   • PHP XML -> sudo apt-get install php-xml
   • PHP mbstring -> sudo apt-get install php-mbstring

That's really it!

Generating This Blog

Important: Before building and uploading your single file blog, be sure to edit all the proper details found inside the _phpetite/_config.php file. This includes your domain, site title, author name, etc.

Most users won't ever need to fiddle with the other files inside the _phpetite directory.

Get PHPetite in order to convert a collection of Markdown files into a single HTML file with inline CSS.

1. Make proper edits to the /_phpetite/_config.php file
2. Write posts in /content
3. (Optional) include any images under the /content/img/ directory
4. From the command-line run:

make

This will generate both the single file HTML page, along with an atom.xml file for the use of an optional RSS feed.

These two files are output into the _site directory.

Looking for more advanced options?

• Adding Custom Pages
• Converting from Jekyll

Adding Custom Pages

To add your own custom pages, simply create a Markdown file under the content/_pages directory. PHPetite will take it from there!

Some Caveats

Any page you create will be automatically added to the footer navigation section. If you wish to hide individual pages from showing in the footer, do so via CSS:

footer a.slug-name-of-your-page {
    display: none;
}

If you want to remove the footer navigation altogether, add the following to your style.css file:

footer .footer-links {
    display: none;
}

About PHPetite

This entire website is a single HTML file. It was generated by PHPetite.

If you notice any issues or want to help make this project even better, check it out on cgit.

Feature Wishlist

☐ Implement a "watch" system for local development (auto-rebuilds)
☐ Detailed documentation for converting existing static sites to PHPetite
☐ More theme / styling options!
☐ Proper accessibility audit
☑ Allow custom fonts to be set as Base64 strings (details here)
☑ Set images as inline Base64 strings
☑ Basic RSS feed
☑ Automatically add new pages to footer nav
☑ Compress inline CSS