Introduction to this website

So, hi! It’s me, le 'amuerta'. I didn’t really plan on making a first post about anything meaningful, nor I had any idea about what I want to write. So let it be about how the process of making posts happen to be.

For quite some time I’ve been thinking about making a personal blog, some sort of website where I will publish my programming dev-logs, art, personal thoughts, reviews, the list goes on… But what was stopping me is the idea that I need to make some sort of environment or system where it’s easy to create and put new posts without putting too much thought into it.

Some might point out that is what social media is made for, and the fact that nobody (yes you are considered nobody) read’s or even knows any blog websites, as those are relic of the past. That is true to some extent, however with social media I have my own gripe - I don’t like them and their concept AT ALL. Most of the current social media activity isn’t about anything interesting, it is mostly just a mindless grind of likes, comments, "subscriptions" and people’s engagement. Instead of sharing fun and useful information, it’s about trends, showing off, reaction baiting or absurdity that is a meme culture. Some of it is fun, but at the end of the day in social media it’s hard to find something honest or interesting for a hyper niche topic a person might be interested, or to find something valuable, that you cannot really see else-were.

After a bit of thinking I realized that there isn’t any point in making concatenation of text a difficult problem. Instead of writing complicated code nobody asked for or needed - I can set up a few scripts that build all the posts from their adoc sources, and appends them in place inside the HTML that acts as a website front end. This way i can simplify post making and make structure of this website way simpler that anticipated.

Simple markup format

I am a very lazy person, and one of the things I hate a lot is document making. Writing text itself is actually perfectly fine, but the moment you introduce "the button hell" that is Microsoft Office or Google Docs, it becomes pretty unpleasant to write anything.

The moment you wanna format something you need to consult your mice, since not every formatting is writable via keyboard shortcuts. And the formatting that is accessible via key strokes are often very bizarre and hard to guess.

Writing on it’s own is actually really fun, whether it’s a paperwork or a hobby.

That’s why i have been using a very handy format for writing documents, ever since i got into college - Asciidoctor.

What is Asciidoctor?

Nearly every programmer or technical person knows about 'Markdown' - a markup file format. It’s used often for creation of quick documents or front pages to projects in documents called 'README'. Also, it can generally be used as replacement for HTML or other similar formats. Markdown brings structure into otherwise - plain text files.

This format is simple and handy, but not nearly enough to write actual paperwork in something like college or research departments. Also, It’s pretty limiting for writing books or really anything that requires more formatting than just having few headings, special formatting for text, lists, and basic images.

That’s exactly where Asciidoctor comes in as a very powerful formatting language that is pretty similar to Markdown. Asciidoctor is written in a very similar fashion as Markdown, but with a lot more to offer in regard to formatting your text work.

Big benefit of this format, that I found nice enough to completely replace MS Word with it, is that with very little effort a very appealing an structured document can be created. When asciidoctor documents are compiled to HTML or PDF they look as good as the one you have to tediously format for your college publication, however this formatting comes from just the format engine itself. Not a single minute is wasted clicking mouse or selecting text to format. Also, this format is just a text, which means no mouse is required nor a very over-complicated editor, all you need is a text editor and asciidoctor utility.

Example of asciidoctor file
= Im your main heading
:toc-title: Stuff in this document
:toc:

== Introduction

I want to introduce **you** to a __very__ handy format - 'adoc'.

.Logo of adoc
image::/path/to/your/image[]

Check it out https://asciidoctor.org[here]

So, how website is build?

Simple, i can have a few root pages:

  • index.html

  • project_1.html

  • project_2.html

  • etc..

They will serve as different pages you consult to get familiar with my activities or big projects I plan for the future, or have already made. On those pages everything that has to be filled from some source of data (like post links, artwork images, output of some sort of command) is enclosed into replacement "tags".

Tag example
<p class="version">This is website commit version: %gitver%</p>

Then inside build script for website i just replace the pattern within a tag with output of command that is run to receive that output.

Script that replaces patterns is called as such
function site_version
	set file ./compiled/index.html
    set replacement (git rev-parse --short HEAD)
    ./replace $replacement (cat $file) "%gitver%" > $file
end

Since this script can call any other script and get its output, I can run and manage entire website of posts as such, and with minimal dependency count! All I need is asciidoctor (which I always have and use) and a script interpreter (in this case it’s fish since I use that shell and quite like it)! That is pretty much all I need to have post’s up and running as fast as I need them to be.

With this I can also generate the posts, which are written in ./posts directory, it’s enough to compile them to html and then generate links to that html which replace a tag in the main page.

Post generation
    # generate posts to cache.txt
    compile_blogs
    generate_links './compiled/posts'
    set replacement (cat cache.txt)
    set file (cat ./compiled/index.html)

    replace "$replacement" "$file" "%post-links%" > ./compiled/index.html

After the full compilation of site a neat compiled directory is organized, this directory can be remotely synced with my hosting and you can see the website change right after a small delay!

compiled folder
assets/
posts/
index.html
style.css

Outro

Well, that is all to say about how this website is made. Hopefully this isn’t too bad for an introductory "Hello world" post. IDK why you would read it up til the end, but either way thanks your for the attention, have a great day! :).