Contemplating Platforms

How I assembled together a product in my spare time.

2026-04-25T00:00:00-07:00

Introducing Terraprep

Introduction

For the longest time I had hesitated on starting the journey of writing a large enough development project outside of my full-time job to keep me busy for months. It was always a mix of “what if no one uses it”, “I don’t know where I might start”, or “can I do it all by myself”.

To be honest, after working in medium to large sized organisations for more than a decade, I got used to much larger than two-pizza teams, layers of politics and relatively slow delivery associated with large organisations. But when it clicked, all I had to do was sit down one evening with intention and start experimenting.

Focus on the MVP

Photo by Ilya Pavlov on Unsplash

The first version was very simple. All you could do was create a simple TOML config file. However, that was sufficient and gave me more than enough confidence to continue.

In the journey I learned that I needed to focus on a complete set of functional requirements. Otherwise I would be creating random ideas instead of a functional set of features.

Lean into the Agile

I have worked in a plethora of varying environments across big data, advertising, insurance and finance industries, with different development methodologies across the board.

For me, this project meant that I needed to be agile while minimising waste. In simple terms, when I started the project all I had was a rough sketch of what I wanted and a blank terminal. No product owners, no backlogs, no sophisticated SDLC.

As I started to build, I had to adapt quickly with my planning, strategy and execution while reducing waste and keeping my focus on a small set of functional features. This pushed me to use tools as and when I needed them. Eventually, towards the end of the beta release, I had a full set of open source and free SDLC tools, in addition to some paid ones, that I use daily for my projects.

X Driven Development

Should I use behaviour driven, test driven or documentation driven development methodology? At first this thought did not even cross my mind.

The reason is that my main skillset is traversing problems in multi-disciplinary technical spaces. I do not have one specific way of doing things. I have to adapt daily, and at times multiple times a day, depending on the team I am working with.

In the end, I used a mix of methodologies depending on what I was trying to achieve at the time.

Dogfooding

Dogfooding means a product created should be used by the creators. This was the original motivation to build this tool.

It was only after building the first few versions myself that I realised it could be turned into a product that others could use. By building this product end to end, I distilled my experience over the years into a system of SDLC tools, mechanisms and methodologies during the project.

Backlog is important

As soon as my first MVP was ready and I could see obvious bugs, fundamental issues and missing functionality that would confuse users, I realised all of those issues had to be tracked.

This forced me to create a backlog, initially just a todo list, that would turn into part of my SDLC toolset. You can do a lot without a complicated backlog, but if you want to collaborate with others while building and releasing a product regularly or semi-regularly, you are better off creating one.

So started my weeks of visualising and backporting all my functional requirements into a backlog that I could continue to use for myself or other collaborators.

Backlog

AI is a friend, not a foe

ChatGPT is the norm these days. Even though I started out by myself, I enjoy collaborating, bouncing ideas off others and getting their feedback.

This is where I truly embraced the tool by OpenAI. Having an incredibly technical sidekick that can validate your ideas and provide opinionated technical perspectives can really boost productivity. Its ability to help debug, write basic test cases and suggest alternative ways of approaching a problem came in handy.

From my personal experience, AI will truly transform the software development space in the coming years. How huge the impact will be is a separate conversation.

Compliment workflows with the right tooling

If there is one bias I have for software development and systems engineering, it is that you must use the right tools, especially if you are working on a sizable and semi-frequently released project.

I have been using JetBrains products for quite a few years, and their tooling for the entire SDLC is incredible. They understand how to build software and are probably one of the biggest examples of dogfooding in the industry.

The language I chose, Go, fits well with the requirements and the user base of the software. It is a cross-platform command-line utility that uses network access and platform APIs to build backends.

Refactor, refactor, refactor

You do not finish a project and throw it over the line, even if it delivers all the functions you had in mind.

It requires consistent prototyping of ideas, building working functionality and refactoring until the entire application aligns with all the instruments that make up the orchestra. During my journey of building this application, I was on a constant cycle of build, test and refactor, to the point that the initial versions of the app do not look anything like the beta release.

Automation is the key

I am an automation enthusiast. That is one of my main skillsets, so I tend not to let opportunities to automate systems and processes go to waste.

When the time came to release the software to a central, publicly available repository, as well as versioned documentation, I did not waste time leveraging pipelines, build processes and automated repeated tasks. I wanted to hand off most of the work to some type of automated job. GitLab is my main way of automating the workflow.

A good tool will productise itself

I did not start the project visualising it as a product. As time went by and my daily practice evolved, I started to think about how I would release the tool and how many other features could be built.

Since I plan to open source parts, or all, of it at some point and collaborate with others, I also wanted to think about how I would achieve that. I did not want users to feel like I was providing subpar software. I wanted them to be able to integrate it into their existing pipelines and workflows.

That forced my hand to make it available in a way that had all the signs of a product. So I thought to myself: why should I not turn this into a product?

Conclusion

The main reason I built this software is so that I can solve the problem for myself, and others, of creating Terraform remote backends.

It is an issue I had noticed since the day I started using Terraform, and I never found a consistent way to solve it. Some suggested doing it manually, others suggested using APIs and scripts. So I decided to create Terraprep.

Terraprep is a cross-platform command-line utility designed to assist users by configuring and deploying Terraform remote backends. It supports creation of multiple backend types and uses interactive prompts and TOML-based configurations. It is available to download at terraprep.xyz.

Originally published on Medium.

Hero image by Milad Fakurian on Unsplash.

On building resilience with React and Rate-limited APIs

2025-12-18T00:00:00-08:00

In the past few months, I have been diving deeper into some of my React adventures that began a few years ago. With more time on my hands lately, I have been able to jump in and build hands-on personal projects to develop a deeper understanding of the React.js ecosystem.

As I refreshed my knowledge of React Hooks, I revisited useEffect and its surprisingly powerful capabilities. Around the same time, I learned that the recent Cloudflare Dashboard outage had something to do with the useEffect hook, so I decided to dig deeper and experiment with a few ideas. Below are the learnings that came out of my investigation.

A little React Primer

For readers who do not know React at all, I will briefly describe the general premise. React is a JavaScript library for building user interfaces, originally created by Facebook. It helps you describe what the UI should look like for a given state.

This is exactly why it is called React. Instead of manually manipulating the DOM with document.getElementById, innerHTML, or jQuery, you describe your UI as components using JSX and let React handle the DOM updates, essentially reacting to changes in state. JSX is a syntax extension that lets you write declarative, HTML-like code inside JavaScript.

Any DOM tree updates are first calculated using what React calls the Virtual DOM before they are diffed and applied to the actual DOM. These updates, or the reactivity, are driven by browser events, user interactions, or custom events. All of these features make React code highly composable, reusable, and performant.

Above is a very simple JSX-based component example where, just by adding a few CSS rules and some state, via props in this case, we transformed a static component into a styled, reusable, and dynamic state-driven UI element. Of course, this is a simple example for demonstration, but hopefully you get the idea.

An extended version of previous app

Hooks and side-effects

Finally, we have React Hooks. Hooks in React are functionality that allow developers to use state and other React features inside function components without needing to write classes. These Hooks, which are just functions, give developers the ability to manage state, handle context, cache values and functions, defer re-renders, and perform other useful tasks.

React Hooks were introduced in v16.8.0. You can see the original release docs here: legacy.reactjs.org/docs/hooks-intro.html

The full list of hooks is available here: react.dev/reference/react/hooks.

One of these hooks is useEffect, which is essentially React’s way of allowing components to synchronise with external systems or APIs, and is commonly used to perform actions when the component loads or when certain state values change.

useEffect(() => {
  // Code to sync with an external system or API.
}, [dependencyArray]);

Before proceeding further, let’s talk about something called side-effects. I am not talking about the ones in medicine, but the idea is the same. An operation has a side effect if it has an observable effect other than its primary one.

In the React world, a side-effect is essentially anything that is outside the control of React’s render cycle. So when we talk about side-effects inside the useEffect hook, we are talking about API calls to external systems, network/fetch requests, or DOM events. These external systems live outside of React’s render cycle, and React has no way to influence them.

If the side-effect is not considered carefully, the useEffect hook may lead to infinite re-renders. This is exactly what caused the self-inflicted DDoS on the Cloudflare dashboard when one of their component’s useEffect hooks introduced a “problematic object in its dependency array”. Let’s dissect that sentence with a concrete example.

Infinite re-renders

Here is another React app that fetches a quote from a public external API. The simple UI renders an <h1>, a <button> tag, and a custom Quote component with a <p> tag holding the current count of quotes.

Quote App

Upon page load, I want the component to automatically fetch a quote, update the state to show the quote, and update quoteCount inside the <p> tag. Finally, when the user clicks on the Get quote button, the function getQuoteFromApi() is triggered to fetch a quote from an external API, update the quote value with a new one, and increment the value of quoteCount.

This is a very common pattern used alongside useEffect in many React applications to interact and sync with external systems on first page load.

useEffect(() => {
  fetchAndSetQuote();
}, []);

Observe an empty array [] is being used as a dependency within the useEffect hook. This tells React to re-render the component if the value of any of the array elements change. Not understanding this, skipping the dependency array, or using a mutable object may lead to an infinite re-render bug.

What can go wrong

Let’s visit the fetchAndSetQuote() function one more time and see the setQuoteCount((c) => c + 1); line, which updates the quoteCount state. It is being updated every time the button is clicked. However, we do not want to re-render the page every time it is updated, hence we do not include quoteCount in the dependency array because useEffect is run on page load.

Let’s see what happens when I add quoteCount to the dependency array or completely skip it.

Problematic dependency array without rate-limited external API

As you can see, we end up with an infinite re-render loop until I stop the process or fix the array object. This is one of the caveats described in the React docs: react.dev/reference/react/useEffect#caveats.

If some of your dependencies are objects or functions defined inside the component, there is a risk that they will cause the Effect to re-run more often than needed. To fix this, remove unnecessary object and function dependencies. You can also extract state updates and non-reactive logic outside of your Effect.

What can be done

In addition to making sure a problematic object, which may cause the Effect to re-run more often than needed, is not introduced in the dependency array, I also mocked up a new service that serves quotes but introduced a rate-limit on how many quotes can be fetched from the service.

When I introduce a problematic object or skip the dependency array altogether within useEffect, I get an infinite re-render loop as before, but my front-end stops making additional re-renders due to rate-limiting.

Wrong dependency array with rate-limited external API

Of course, this is an oversimplification of what may have happened at Cloudflare, and it is possible that the engineering team at Cloudflare were already aware of useEffect caveats and working towards fixing it before it became a big problem. Finally, a mix of these things led to a perfect storm, or as they mention, a thundering herd.

Having said all that, I can see that Cloudflare are looking for a frontend-focused platform engineer for their Dashboard and associated services. Not surprising at all.

Must I use useEffect

There are alternatives that have been suggested over the last few years, and two of the most popular ones are TanStack Query, through useQuery, and Redux, through RTK Query. They both provide solutions to make use of safer ways to fetch data from external APIs.

TanStack & Redux

useQuery from TanStack

Remember, these are pretty comprehensive libraries/frameworks, allowing you to manage state lifecycle and a plethora of other features. Their use is tied to the requirements and the complexity matrix. It is a trade-off that only engineering and product teams can decide on collectively.

In closing

My exploration led me to a simple conclusion. I call it React’s KISS.

It is becoming increasingly necessary to understand modern frontends, their architecture and usage of external services, as well as building resilience through patterns that can help minimise these issues.

With the trend of increased AI usage, we must become more diligent about the resilience, security, and availability of our systems, especially if those systems are playing a crucial role in our day-to-day lives.

Originally published on Medium/FAUN.

Hero image by Tim Käbel on Unsplash.

Upgrading Guide from v1 to v2

2018-07-23T00:00:00-07:00

Almace Scaffolding now migrates from Less to Sass, this may make your existing projects non-upgradable, it needs quite a lot of work for you to do the migration if you use a custom theme that it’s powered by Less preprocessor. You have to compare your existing projects to this Pull Request side to side to make sure every change you made are synced correctly.

If you’re a casual blogger only change some color variables for your default theme, Curtana in this situation, that’s good, you can migrate to v2 easier: just run $ grunt update.

You should also migrate your own styles in user.less to _user.scss and _varaibles.scss. Due to Sass limitation, I don’t have variable hoisting features like native CSS or Less at hand, so I have to create two user-defined stylesheets:

assets/_scss/_variables.scss - This file should contain only Sass variables defined in theme Curtana. It will be loaded at the topmost of theme stylesheet app.scss.
assets/_scss/_user.scss - where users create style customization.

From 2.0.0, Almace Scaffolding still has the ability to use Less with Grunt.js, however, it’s wise to write your theme in Sass for better future compatibility.

If you’d like to stick with the Less version:

v1.1.11 will be the last version that supports Less.
Less version of theme Curtana will be available as amsf/amsf-curtana-less.

Upgrading Guide: v1.1.0

2017-01-07T00:00:00-08:00

There’re some significant changes in update v1.1.0, action required after you upgrade Almace Scaffolding.

In your front-matter fields:

Replace all svg-headline, img-headline with heading-img.
Replace all svg-headline-width, img-headline-width with heading-img-width.
Remove all svg-headline-height, img-headline-height as they’re deprecated and no longer available.
Add heading-img-local: true if images are stored right inside your project.

Check the following front-matter data for post thumbnails:

Replace all thumb with thumbnail.
Add thumb/ prefix to your filename, ie. thumbnail: thumb/my-post.png.
Add thumbnail-local: true if thumbnails are stored right inside your project.

Open Graph

2017-01-06T00:00:00-08:00

Theme Curtana has full Open Graph and Twitter Cards support.

It will look for the image in the following order:

Use page.thumbnail if defined in your post front-matter field.
If no specified page.thumbnail defined, it uses Heading Background Image (aka. page.heading-bg) if defined in your post front-matter field.
If no heading background image found, Curtana will try to grab the first image (wrapped inside <img>) in your post as your post thumbnail
If nothing found, it falls back to logo.png located at your site root.

You can always use page.thumb_force_logo in your post’s front-matter field to override the above lookup.

Here’s a preview on Twitter:

Jekyll Theme Compatibility

2016-11-07T00:00:00-08:00

With the recent release of Jekyll, it gets the built-in ability to support themes, since we’ve already added theme support in 2015, the original config variables theme would be conflicted with the built-in one.

To solve this issue, I’ve renamed our theme option to amsf_theme. And here’s what you need to do to resolve compatibility issues after upgrading to latest Almace Scaffolding:

Rename your original theme option in _amsf.yml to amsf_theme.
Add amsf_theme_url with your theme Git URL.
Replace all site.theme with site.amsf_theme in your page templates.

Introducing Curtana

2016-06-01T00:00:00-07:00

Curtana is the default theme of AMSF (Almace Scaffolding).

Features

A variant of sparanoid.com, looking great on any modern browsers
Minimalism design, No jQuery, no everybody-shake-ur-body.js
Ideal for the personal blog, portfolio, product blog and Tumblr-like link blog
(Maybe) the first template that uses viewport relative units
Handcrafted stylesheets. No Bootstrap or other bloated frameworks are used, unminified CSS < 12 KB
Predefined CSS and Sass (SCSS) variables make it easier to change color schemes for posts
Dynamic color scheme for code highlighters powered by Randomized
Open Graph and Twitter Cards support
No Internet Explorer support

Deployment Methods

2016-03-18T00:00:00-07:00

Sites generated using Almace Scaffolding can be deployed in nearly any web hosting services. A few of the most common deployment techniques are described below. More deployment methods please refer to Jekyll - Deployment methods.

Cloudflare Pages

The simplest way to deploy your AMSF site is using Cloudflare Pages. Just signup for Cloudflare and connect it with your GitHub account. Create a Pages project and use the following settings:

Framework preset: Jekyll
Build command: grunt build
Build output directory: _site

Web Hosting Providers (FTP/SFTP)

Just about any traditional web hosting provider will let you upload files to their servers over FTP. You can simply run the grunt build command and upload all files generated under _site to the HTTP root folder of your hosting account.

rsync

There’s a _deploy.yml at the root of your AMSF project containing a basic rsync configurations. Change these configurations to yours and then run:

$ grunt deploy:rsync

You can deploy it for specific environments, the following command will deploy your site to beta environment via rsync method you defined in _deploy.yml:

$ grunt deploy:rsync --env=beta

Amazon S3 (s3_website)

You can also deploy your site to Amazon S3 via s3_website, see s3_website.example.yml for more info.

Multiple Themes Support

2015-08-18T00:00:00-07:00

From version 0.0.31, you can now use multiple themes in Almace Scaffolding. See Themes for more information.

Welcome

2014-06-13T00:00:00-07:00

AMSF, a.k.a. Almace Scaffolding, is a super-fast Jekyll framework fighting against the website obesity. It supports LiveReload, Sass, HTML minification, inlined stylesheets and more.

Getting Started →

Go to the GitHub page for downloads, bug reports, and feature requests.

Features

Theme switching, you can switch themes with just one command
A fully configured Jekyll setup with well-defined Atom feed and sitemap
Almace Scaffolding ships a sleek responsive theme Curtana, a variant of sparanoid.com, looking great on any modern browsers
Every minified page generates only one HTTP request ¹
Tons of configurable settings for your posts and site customization
Service Worker support for lightning-fast experience
Built with Grunt.js for easy development
Travis support

Based on the theme you’re using, theme Curtana generates only one HTTP request for production build when your posts don’t have fancy sliders or other external media files. ↩︎

Getting Started

2014-06-12T00:00:00-07:00

Requirements
Method: Run in Docker
- Custom Dependencies
Method: Run Locally
- Upgrading
- Using Beta Release
Download
Jekyll Migration

Requirements

Almace Scaffolding has exactly the same requirements as Jekyll. For more info please refer to Installation - Jekyll.

Method: Run in Docker

You can simply run Almace Scaffolding in Docker with compose command. Create your own docker-compose.yml file with the following content:

version: '3'

x-defaults: &defaults
  image: sparanoid/almace-scaffolding:latest
  restart: always
  volumes:
    - ./_app/_posts/:/app/_app/_posts/
  ports:
    - "4321:4321"

services:
  amsf:
    <<: *defaults
    command: serve

This is a minimal docker compose configuration with local _posts volume mounted inside the container. The volumes option can be different based on your customization.

Mount custom data, pages, posts to override them inside container:

...
  volumes:
    - ./_app/_data/:/app/_app/_data/
    - ./_app/_pages/:/app/_app/_pages/
    - ./_app/_posts/:/app/_app/_posts/

Override config file:

...
  volumes:
    - ./_config.yml:/app/_config.yml

Use custom Gruntfile:

...
  volumes:
    - ./Gruntfile.coffee:/app/Gruntfile.coffee

Use custom AMSF config for custom themes and templates:

...
  volumes:
    - ./_app/:/app/_app/
    - ./_site/:/app/_site/
    - ./_amsf.yml:/app/_amsf.yml

You can see the example repo at amsf/docker-amsf-example.

Custom Dependencies

You can load custom dependencies (custom Grunt plugins or Jekyll plugins) in Docker by building your own Docker images. First you need to create a Dockerfile:

FROM sparanoid/almace-scaffolding:latest

# Copy custom dependencies configs
COPY Gemfile* /app/
COPY package.json /app/package.json
COPY yarn.lock /app/yarn.lock

# Reinstall project specific dependencies
RUN bundle install && yarn install

Then build your image with Docker Compose:

version: '3'

x-defaults: &defaults
  build:
    context: .
    dockerfile: Dockerfile
...

Method: Run Locally

Fork or clone the repo.
Install dependencies with Ruby gem bundler and Node.js package manager npm.
Run grunt init to initialize your project.
Run grunt serve to fire up a local server.
Edit and customize your site.
Change Git remote to your own repo.
Push and deploy.

So in short for geeks:

$ git clone https://github.com/sparanoid/almace-scaffolding my-site
$ cd my-site
$ bundle install && yarn install
$ grunt init
$ grunt serve
# ...editing
$ git remote set-url origin https://github.com/sparanoid/my-site.git
$ git push -u origin master
# ...publishing
$ grunt && grunt deploy:rsync --env=prod

Upgrading

It will be easy if you’re a casual blogger and keep every core and template file untouched. You can use the following command to update Almace Scaffolding core files:

$ grunt amsf-update

It checks the latest Almace Scaffolding build from GitHub and updates core files automatically. Please keep in mind that if you changed some of the AMSF core files this action will override the changes you made. So it’s recommended to keep your project under version control, you will always be able to compare changes for Almace Scaffolding.

Using Beta Release

By default, when you run amsf-update you will get updated files from release branch. However, I’m continuously working on Almace Scaffolding, so there may have testing branches you can try and give me feedback if you’re interested. You can check the AMSF GitHub repository for available branches, and it’s very easy to switch:

$ grunt amsf-update --branch=feat/service-worker

The branch master is the one which is always available to check out and also has the latest changes:

$ grunt amsf-update --branch=master

If you messed up with the testing branch, don’t worry, you can just run a normal update to revert them back:

$ grunt amsf-update

Download

Go to the GitHub repository for downloads, bug reports, and feature requests.

Jekyll Migration

You can simply copy all posts from your old Jekyll setup into _app/_posts, you can also transfer your custom pages into _app/_pages/.

Customizing Styles

2014-06-11T00:00:00-07:00

You can customize the basic look and feel without touching the theme files by changing user.js and user.scss:

├── _app/
|   ├── assets/
|   |   └── _js/
|   |   |   └── user.js
|   |   └── _scss/
|   |   |   └── user.scss
|   |   └── themes/
|   |   |   └── ...

These files won’t be overwritten when you update Almace Scaffolding or update your themes.

Configuration

2014-06-11T00:00:00-07:00

Configuration Settings

All AMSF built-in settings can be configured at _config.yml.
Theme specific variables can be found at ./_app/_data/theme-name.yml.
Additional variables are stored in ./_app/_data/ directory. They can be accessed by Jekyll. (More info)
You should also change favicon.* and apple-touch-icon.png to yours.
logo.png is mainly used by Open Graph and Twitter Cards when there’s no featured image in a post, you should also design your own.
More customization please refer to theme-specific documentation

Tips

Not familiar with Markdown? Try Markdown Cheatsheet.
You can use Jekyll’s built-in syntax highlighting, I’ve included a default theme for this project.
Tables and footnotes are also available to use.

Themes

2014-06-10T00:00:00-07:00

Overview

In the latest build, I’ve added multiple themes support, finally, you can switch themes with just one command.

This is an experimental feature and may change until the feature stabilizes.

Installing Themes

The AMSF framework ships a default theme Curtana. You can also install as many themes as you like and switch to the one you prefer at any time.

Via Git (GitHub)

The easiest way to install a new theme is via theme-add, the following command will install theme Curtana from its official repo amsf/amsf-curtana:

$ grunt theme-add --theme=curtana

If you’d install a custom theme from other users, append --user in your command, the following command will install a new theme named bootstrap-sass from sparanoid/amsf-bootstrap-sass

$ grunt theme-add --theme=bootstrap-sass --user=sparanoid

Manually Install

You can also install themes manually. find an AMSF theme (Curtana, for example), download the package and uncompress all files to .amsf-cache/themes directory, the file structure should look like:

├── .amsf-cache/ (Almace Scaffolding cache directory)
|   ├── themes/
|   |   └── curtana/
|   |   |   └── assets/
|   |   |   └── includes/
|   |   |   └── layouts/
|   |   |   └── pages/
|   |   |   └── config.yml
└── _app/

Then execute the following command:

$ grunt activate --theme=curtana

Your current theme will be backed up to .amsf-cache/themes/your-old-theme/ and the new theme curtana will be installed to the appropriate directories.

Upgrading Themes

You can update your current activated theme by the following command. The activated theme will be downloaded from GitHub automatically if there’s any update:

$ grunt theme-update

Please note that only themes added via GitHub can be updated.

Creating Your Own Theme

2014-06-09T00:00:00-07:00

Overview

You can create your own theme in AMSF, theme files are located in the following location (I use default theme Curtana here for better understanding):

├── _app/
|   ├── _data/
|   |   └── curtana.yml
|   ├── _includes/
|   |   └── themes/
|   |   |   └── curtana/
|   |   |   |   └── includes/
|   |   |   |   └── layouts/
|   ├── _pages/
|   |   └── themes/
|   |   |   └── curtana/
|   |   |   |   └── example-page.md
|   |   |   |   └── ...
|   ├── assets/
|   |   └── themes/
|   |   |   └── curtana/
|   |   |   |   └── _js/
|   |   |   |   └── _scss/
|   |   |   |   └── ...

The theme specific config curtana.yml should have the same filename as your theme name. It should contain theme-specific variables and can also override AMSF built-in settings.

More info about theme structure you can check out my default theme Curtana.

You can also have multiple themes in your project, as many as you like. For example if you also have themes Bootstrap and Ghost installed, the file structure should be:

├── _app/
|   ├── _data/
|   |   └── bootstrap.yml
|   |   └── curtana.yml
|   |   └── ghost.yml
|   ├── _includes/
|   |   └── themes/
|   |   |   └── bootstrap/
|   |   |   |   └── includes/
|   |   |   |   └── layouts/
|   |   |   └── curtana/
|   |   |   |   └── includes/
|   |   |   |   └── layouts/
|   |   |   └── ghost/
|   |   |   |   └── includes/
|   |   |   |   └── layouts/
|   ├── _pages/
|   |   └── themes/
|   |   |   └── bootstrap/
|   |   |   |   └── example-about.md
|   |   |   |   └── example-blog.md
|   |   |   |   └── example-fluid-container.md
|   |   |   |   └── ...
|   |   |   └── curtana/
|   |   |   |   └── example-about.md
|   |   |   |   └── example-news.md
|   |   |   |   └── ...
|   |   |   └── ghost/
|   |   |   |   └── example-archive.md
|   |   |   |   └── example-page.md
|   |   |   |   └── example-tagcloud.md
|   |   |   |   └── ...
|   ├── assets/
|   |   └── themes/
|   |   |   └── bootstrap/
|   |   |   |   └── _coffee/
|   |   |   |   └── _scss/
|   |   |   |   └── images/
|   |   |   └── curtana/
|   |   |   |   └── _js/
|   |   |   |   └── _scss/
|   |   |   |   └── svg/
|   |   |   └── ghost/
|   |   |   |   └── _js/
|   |   |   |   └── _less/
|   |   |   |   └── fonts/
...

AMSF Options

There’re several built-in options you can use in your theme. These options can also be overridden in theme-specific config.

`site.name`

Template:

<footer class="footer">
  <ul>
    <li><a href="/">{{ site.name }}</a></li>
    <li><a href="/atom.xml">Atom</a></li>
  </ul>
</footer>

Output:

<footer class="footer">
  <ul>
    <li><a href="/">Almace Scaffolding</a></li>
    <li><a href="/atom.xml">Atom</a></li>
  </ul>
</footer>

`site.description`

Site description will appear in the document meta and Atom feed subtitle.

Template:

<meta property="og:description" content="{{ site.description }}">

Output:

<meta property="og:description" content="A super-fast Jekyll framework fighting against the website obesity.">

`site.file`

Media assets URL used in posts, without trailing slash. In most cases this URL should be powered by a CDN provider.

Config:

file: //d349cztnlupsuf.cloudfront.net

Template:

<img src="{{ site.file }}/post-thumbnail.jpg">

Output:

<img src="//d349cztnlupsuf.cloudfront.net/post-thumbnail.jpg">

`site.twitter`

Site Twitter account handle.

Template:

<a href="https://twitter.com/{{ site.twitter }}">Follow @{{ site.twitter }} on Twitter</a>

Output:

<a href="https://twitter.com/sparanoid">Follow @sparanoid on Twitter</a>

`site.force_utf_8`

Force UTF-8 encoding, enable this will simply add <meta charset="utf-8"> to the head of your pages.

Template:

{% if site.force_utf_8 %}
  <meta charset="utf-8">
{% endif %}

`site.robots`

You can define your own records in robots.txt.

Config:

robots:
  - "User-agent: *"
  - "Disallow: /ajax/"
  - "Disallow: /@async"
  - "Disallow: /log/"

Theme Features

There’re some features can be integrated into your theme.

(Basic) Multi-Language Support

You can define post/page language in your front-matter field:

lang:
  - zh-tw

An additional lang HTML attribute will be added to your final rendering:

<article lang="zh-tw">
  ...
</article>

If your post/page content is multilingual, you can also define multiple languages in array:

lang:
  - zh-tw
  - en-us

Please note that only the first item defined in lang array will be used in final lang output, the additional languages will be available in JSON feed output:

{
  "languages": ["zh-tw", "en-us"],
  "categories": ["note"],
  "tags": ["miscellaneous"]
}

Smooshing Assets

For better performance, Almace Scaffolding will find all the CSS, script links and images in compiled HTML, and outputs a version with all the CSS, scripts and images (Base64) written inline. Sounds cool? but it needs theme support. Here’s how:

You can simply add the query string ?assets-inline at the end of the file you’d like to be inlined in production site:

<!-- This CSS will be inlined into HTML -->
<link rel="stylesheet" href="{{ '/css/app.css?assets-inline' | prepend: amsf_theme_assets }}">

<!-- This script will be inlined into HTML -->
<script src="{{ '/js/app.js?assets-inline' | prepend: amsf_theme_assets }}"></script>

User Custom Styles Support

Define the following code snippet into your theme styles (Sass) will allow users to custom your theme without touching the theme files:

// Import user custom styles
@import "../../../_scss/custom";

User Custom Scripts Support

Define the following code snippet into your theme template (it’s recommended to put it in footer) will allow users to add custom scripts without touching the theme files:

<!-- User custom scripts -->
<script src="{{ '/js/user.js?assets-inline' | prepend: amsf_user_assets }}"></script>

Page / Post Specific CSS Block Support

This allows your user to define page / post specific CSS blocks in front-matter data:

<!-- Page-wide custom CSS -->
{{ amsf_page_css }}

Google Analytics Support

This allows your user to be able to use Google Analytics for their site, tracking ID can be changed in the config file:

<!-- Google Analytics tracking code -->
{{ amsf_google_analytics }}

Post Published Time

This allows you to get the published time of the current post.

Template:

<meta property="article:published_time" content="{{ amsf_page_pubdate | date_to_xmlschema }}">

Output:

<meta property="article:published_time" content="2014-01-01T00:00:00+08:00">

Post Modified Time

This allows you to get the modified time of the current post.

Template:

<meta property="article:modified_time" content="{{ amsf_page_update | date_to_xmlschema }}">

Output:

<meta property="article:modified_time" content="2014-01-03T03:17:49+08:00">

Post Reading Time

This allows you to show the average reading time of current post.

Template:

Reading time: {{ amsf_page_reading_time }}

Output:

# Less than 200 words
Reading time: Less than 1 min

# Around 200 words
Reading time: 1 min

# More than 200 words
Reading time: 34 mins

# More than 1 hour
Reading time: 1 hr
Reading time: 1 hr 1 min
Reading time: 3 hrs 20 mins

Publishing Themes

You really like your custom design and wanna show it off to the world? Cool, you can create (pack) you own theme by the following command:

$ grunt theme-save

The activated theme will be saved to AMSF cache (.amsf-cache/) with correct file and directory structure, then you can upload your theme to GitHub.

Still confusing? see my default theme Curtana for reference.

Syntax Highlighting

2014-06-06T00:00:00-07:00

Code highlighting demo, powered by Rouge. More info about code highlighting can be found at Jekyll’s documentation.

.code-text (@link, @text) when (lightness(@link) >= 50%) and (lightness(@link) < lightness(@text)) {
  @return-color: lighten(@text, 20%);
  @return-value: 30%;
}

{
  "scripts": {
-   "precommit": "npm test",
-   "commitmsg": "commitlint -E GIT_PARAMS"
  },
+ "husky": {
+   "hooks": {
+     "pre-commit": "npm test",
+     "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+   }
+ }
}

def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end

echo "Hello, world!";

def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

1
2
3
4
5
6
7
8
9
10
11
12
<!doctype html>
<html>
  <head>
    <title>Title!</title>
  </head>
  <body>
    <h1 id="title" class="heading">Example</h1>
    <p id="foo">Hello, World!</p>
    <script type="text/javascript">var a = 1;</script>
    <style type="text/css">#foo { font-weight: bold; }</style>
  </body>
</html>

// Load the http module to create an http server.
var http = require('http');

// Configure our HTTP server to respond with Hello World to all requests.
var server = http.createServer(function (request, response) {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.end("Hello World\n");
});

// Listen on port 8000, IP defaults to 127.0.0.1
server.listen(8000);

// Put a friendly message on the terminal
console.log("Server running at https://127.0.0.1:8000/");

.code-text (@link, @text) when (lightness(@link) >= 50%) and (lightness(@link) < lightness(@text)) {
  @return-color: lighten(@text, 20%);
  @return-value: 30%;
}

<!doctype html>
<html>
  <head>
    <title>Title!</title>
  </head>
  <body>
    <h1 id="title" class="heading">Example</h1>
    <p id="foo">Hello, World!</p>
    <script type="text/javascript">var a = 1;</script>
    <style type="text/css">#foo { font-weight: bold; }</style>
  </body>
</html>

; copied from https://llvm.org/docs/LangRef.html#module-structure
; Declare the string constant as a global constant.
@.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"

; External declaration of the puts function
declare i32 @puts(i8* nocapture) nounwind

; Definition of main function
define i32 @main() {   ; i32()*
  ; Convert [13 x i8]* to i8  *...
  %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0

  ; Call puts function to write out the string to stdout.
  call i32 @puts(i8* %cast210)
  ret i32 0
}

; Named metadata
!1 = metadata !{i32 42}
!foo = !{!1, null}

<?xml version="1.0" encoding="utf-8"?>
<xsl:template match="/"></xsl:template>

util = require "my.module"

a_table = {
  foo: 'bar'
  interpolated: "foo-#{other.stuff 2 + 3}"
  "string": 2
  do: 'keyword'
}

class MyClass extends SomeClass
  new: (@init, arg2 = 'default') =>
    @derived = @init + 2
    super!

  other: =>
    @foo + 2

AddDefaultCharset UTF-8

RewriteEngine On

# Serve gzipped version if available and accepted
AddEncoding x-gzip .gz
RewriteCond %{HTTP:Accept-Encoding} gzip
RewriteCond %{REQUEST_FILENAME}.gz -f
RewriteRule ^(.*)$ $1.gz [QSA,L]
<FilesMatch \.css\.gz$>
  ForceType text/css
  Header append Vary Accept-Encoding
</FilesMatch>
<FilesMatch \.js\.gz$>
  ForceType application/javascript
  Header append Vary Accept-Encoding
</FilesMatch>
<FilesMatch \.html\.gz$>
  ForceType text/html
  Header append Vary Accept-Encoding
</FilesMatch>

diff(plus(A,B), X, plus(DA, DB))
   <= diff(A, X, DA) and diff(B, X, DB).

diff(times(A,B), X, plus(times(A, DB), times(DA, B)))
   <= diff(A, X, DA) and diff(B, X, DB).

equal(X, X).
diff(X, X, 1).
diff(Y, X, 0) <= not equal(Y, X).

(* Binary tree with leaves car­rying an integer. *)
type tree = Leaf of int | Node of tree * tree

let rec exists_leaf test tree =
  match tree with
  | Leaf v -> test v
  | Node (left, right) ->
      exists_leaf test left
      || exists_leaf test right

let has_even_leaf tree =
  exists_leaf (fun n -> n mod 2 = 0) tree

SELECT * FROM `users` WHERE `user`.`id` = 1

quadMultiply: i1 and: i2
    "This method multiplies the given numbers by each other
    and the result by 4."
    | mul |
    mul := i1 * i2.
    ^mul * 4

#lang racket

;; draw a graph of cos and deriv^3(cos)
(require plot)
(define ((deriv f) x)
  (/ (- (f x) (f (- x 0.001))) 0.001))
(define (thrice f) (lambda (x) (f (f (f x)))))
(plot (list (function ((thrice deriv) sin) -5 5)
            (function cos -5 5 #:color 'blue)))

;; Print the Greek alphabet
(for ([i (in-range 25)])
  (displayln
   (integer->char
    (+ i (char->integer #\u3B1)))))

;; An echo server
(define listener (tcp-listen 12345))
(let echo-server ()
  (define-values (in out) (tcp-accept listener))
  (thread (λ ()
             (copy-port in out)
             (close-output-port out)))
  (echo-server))

service { 'ntp':
  name      => $service_name,
  ensure    => running,
  enable    => true,
  subscribe => File['ntp.conf'],
}

void main() {
  var collection=[1,2,3,4,5];
  for(var a in collection){
    print(a);
  }
}

proc cross_sum {s} {expr [join [split $s ""] +]}

// reverse byte order (16-bit)
public static UInt16 ReverseBytes(UInt16 value)
{
  return (UInt16)((value & 0xFFU) << 8 | (value & 0xFF00U) >> 8);
}

Private Sub Form_Load()
    ' Execute a simple message box that says "Hello, World!"
    MsgBox "Hello, World!"
End Sub

def fib(n):    # write Fibonacci series up to n
    """Print a Fibonacci series up to n."""
    a, b = 0, 1
    while a < n:
        print a,
        a, b = b, a+b

#!/usr/bin/env perl
use warnings;
print "a: ";
my $a = "foo";
print $a;

Markdown has cool [reference links][ref 1]
and [regular links too](https://example.com)

[ref 1]: https://example.com

- name: set PHP-FPM parameters
  lineinfile:
    dest: /etc/php-fpm.conf
    regexp: "^"
    insertafter: "^;"
    line: " = "
  with_items:
    - { param: 'error_log', value: '/var/log/php-fpm/error.log' }
    - { param: 'log_level', value: 'error' }
    - { param: 'emergency_restart_threshold', value: '10' }

Markdown Features Test

2014-06-06T00:00:00-07:00

Indented Code Blocks

def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end

Liquid Tag with `linenos` Support

1
2
3
4
5
6
7
def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end

GFM Code Blocks (`fenced_code_blocks`)

/* Background color function */
.code-bg (@v) when (lightness(@v) >= 50%) {
  @return-bg: mix(#000, lighten(@v, 30%), 10%);
}
.code-bg (@v) when (lightness(@v) < 50%) {
  @return-bg: mix(#fff, darken(@v, 10%), 70%);
}

SmartyPants

“Aha! What’s up, man?” – Jony said.

Tables

Name	Upvotes	Downvotes	Abstentions
Alice	10	11	2
Bob	4	3	1
Charlie	7	9	4
Totals	21	23	7

Intra-emphasis

foo_bar_baz

Auto-link

https://sparanoid.com/

Strikethroughs

This is ~~good~~ bad.

Space after Headers

###This is not a header.

Superscripts

This is the 2^(nd) time.

Footnotes

This¹ is² a sentence³.

ID 日本語タイトル

Expected id should be id-ri-ben-yu-taitoru.

ID 中文標題

Expected id should be id-zhong-wen-biao-ti.

Lorem lean startup ipsum product market fit customer development acquihire technical cofounder. User engagement A/B testing shrink a market venture capital pitch deck. Social bookmarking group buying crowded market pivot onboarding freemium prototype ping pong. Early stage disruptive ecosystem community outreach dynamic location based strategic investor. ↩︎
An Important Announcement by Richard Ziade at Readability ↩︎
Good afterble constanoon, this sweet hongi is as bung as a stuffed morepork. Mean while, in the marae, Dr Ropata and Hairy Maclary from Donaldson’s Dairy were up to no good with a bunch of bloody troties. ↩︎

Markup Example

2014-06-05T00:00:00-07:00

Lorem lean startup ipsum product market fit customer development acquihire technical cofounder. User engagement A/B testing shrink a market venture capital pitch deck. Social bookmarking group buying crowded market pivot onboarding freemium prototype ping pong. Early stage disruptive ecosystem community outreach dynamic location based strategic investor.

Two days ago the Chinese website Taobao held a discount promotion to celebrate what’s known as “double sticks day” in China. In a single 24hr period, they conducted 19bn RMB (US$3.06bn) of business.

Chris West

Curabitur blandit tempus porttitor. Nullam quis risus eget urna mollis ornare vel eu leo. Nullam id dolor id nibh ultricies vehicula ut id elit.

Good afterble constanoon, this sweet hongi is as bung as a stuffed morepork. Mean while, in the marae, Dr Ropata and Hairy Maclary from Donaldson’s Dairy were up to no good with a bunch of bloody troties.

Inline HTML elements

HTML defines a long list of available inline tags, a complete list of which can be found on the Mozilla Developer Network.

To bold text, use <strong>.
To italicize text, use <em>.
Abbreviations, like HTML should use <abbr>, with an optional title attribute for the full phrase.
Citations, like — Sparanoid & Mark otto, should use <cite>.
~~Deleted~~ text should use <del> and inserted text should use <ins>.
Superscript ^text uses <sup> and subscript _text uses <sub>.

With the exception of Nietzsche, no other madman has contributed so much to human sanity as has Louis Althusser. He is mentioned twice in the Encyclopaedia Britannica as someone’s teacher. There could be no greater lapse: for two important decades (the 60s and the 70s), Althusser was at the eye of all the important cultural storms. He fathered quite a few of them.
This newly-found obscurity forces me to summarize his work before suggesting a few (minor) modifications to it.
- Society consists of practices: economic, political and ideological.
  - Althusser defines a practice as:
  - “Any process of transformation of a determinate product, affected by a determinate human labour, using determinate means (of production)”
    - The economic practice (the historically specific mode of production) transforms raw materials to finished products using human labour and other means of production, all organized within defined webs of inter-relations. The political practice does the same with social relations as the raw materials. Finally, ideology is the transformation of the way that a subject relates to his real life conditions of existence.
      - This is a rejection of the mechanistic worldview (replete with bases and superstructures). It is a rejection of the Marxist theorization of ideology. It is a rejection of the Hegelian fascist “social totality”. It is a dynamic, revealing, modern day model.
      - “The objective internal reference … the system of questions commanding the answers given”
    - Subjects to what? The answer: to the material practices of the ideology. This (the creation of subjects) is done by the acts of “hailing” or “interpellation”. These are acts of attracting attention (hailing) , forcing the individuals to generate meaning (interpretation) and making them participate in the practice.
      - Subjects to what? The answer: to the material practices of the ideology. This (the creation of subjects) is done by the acts of “hailing” or “interpellation”. These are acts of attracting attention (hailing) , forcing the individuals to generate meaning (interpretation) and making them participate in the practice.
      - What happens in a pluralistic environment rich in competing ideologies?
        
        Clarifying the HOW, though, does not shed light on the WHY.
        
        is the fact that in the new one, the second text is articulated with the lapses in the first text … (Marx measures) the problematic contained
    - Ideology is a practice with lived and material dimensions. It has costumes, rituals, behaviour patterns, ways of thinking. The State employs Ideological Apparatuses (ISAs) to reproduce ideology through practices and productions: (organized) religion, the education system, the family, (organized) politics, the media, the industries of culture.
These theoretical tools were widely used to analyze the Advertising and the film industries.

Ordered list
Ordered list
1. Ordered list
  1. Ordered list
  2. Ordered list
    1. Ordered list
      1. Ordered list
      2. Ordered list
    2. Ordered list
      1. Ordered list
    3. Ordered list
2. Ordered list
  1. Ordered list
  2. Ordered list
Ordered list

“This should be replaced.”

This is a normal paragraph.

‘This should be replaced.’

This is a normal paragraph.

「This should be replaced.」

This is a normal paragraph.

『This should be replaced.』

This is a normal paragraph.

（This should be replaced.）

This is a normal paragraph.

Most of these elements are styled by browsers with few modifications on our part.

Maui and his rough as guts piece of pounamu, what a stink buzz. Bro, quater-acre patches are really naff good with bung mates, aye. You have no idea how beached as our random kais were aye. Every time I see those beautiful lengths of number 8 wire it’s like Castle Hill all over again aye, do you happen to have a bucket or a hose bro?

H2 Headings

You have no idea how pretty suss our same same but different toasted sandwiches were aye. Every time I see those carked it keas it’s like the dairy all over again aye, you don’t know his story, bro. Anyway, Hairy Maclary from Donaldson’s Dairy is just Mrs Falani in disguise, to find the true meaning of life, one must start frying up with the hangi, mate. After the rugby ball is jumped the ditch, you add all the stink girl guide biscuits to the trotie you’ve got yourself a meal.

H3 Headings

H4 Headings

H5 Headings

H6 Headings

He was alone then; when he sat in that same chair his wife now sits in, and I shared with him the positive result to his HIV test. Though he seemed disinterested, vaguely detached, he had obviously heard of HIV before. His chart from the local clinic indicated a previous history of and treatment for anal gonorrhea, two acute cases of syphilis in the past three years, and a urinary tract infection last month. His only listed sexual contact, his wife. Who, strangely enough, only tested positive for one of the syphilis infections.

“Mistake, this! I am married, not a giver of ass.”

Giver of ass? That’s one for the archive, I think.

Unwilling to engage his obvious denials, I ignore the comment and instead explain that due to a higher than acceptable potential of a false positive result, we won’t consider his oral test as confirmatory until the more accurate blood analysis is in.

“I no understand”, he says to the room in general.

His annoyance is obvious. Abrasively, he offers me his exposed forearm. This, I assume, is my cue to draw his blood. Ignoring the indignant anger beginning to rise, I tighten my jaw, then swab the fat vein with betadine, working the cool, brown liquid off in concentric circles, using strong medicinal smelling alcohol. I use the betadine, as most of these men work in the mines, and dirt three layers thick on exposed skin is the norm. As the first tube in the vacationer fills with blood, he asks,

“So how I get this thing?”

Ah, I see we are going to play the circuitous dance of ignorance. Sounding just a little too clinical, I begin the HIV 101 mantra.

“Well, people acquire HIV through certain types of sex with an infected person, through sharing needles with an infected person, and sometimes through a blood transfusion. Have you ever had a blood transfusion, sir?”

I take the dismissive wave of his hand as a no to the transfusion question. I don’t make a great attempt to navigate a comfort zone here; instinct and experience telling me he has already set the script of what is to follow.

“She is fucking other cocks my whore devil wife”? Bingo! A narrative that over the next six weeks I will hear from several other men as well.

“These whores, all they want is the cock!” Careful Skippy, you really aren’t as convincing as you think you are.

“She is fucking other cocks my whore devil wife”?
Bingo! A narrative that over the next six weeks I will hear from several other men as well.

“These whores, all they want is the cock!”
Careful Skippy, you really aren’t as convincing as you think you are.

from A World Away by alto

Supported Fonts

Chinese Paragraph

「名词成灾」的流行病里，灾情最严重的该是所谓「科学至上」（scientism）。在现代的工业社会里，科学早成显贵，科技更是骄子，所以知识分子的口头与笔下，有意无意，总爱用一些「学术化」的抽象名词，好显得客观而精确。有人称之为「伪术语」（pseudo-jargon）。例如：明明是 first step，却要说成 initial phase：明明是 letter，却要说成 communication，都属此类。

Japanese Paragraph

『雪国』の主な舞台は、上越国境の清水トンネルを抜けた湯沢温泉であるが、この作品も『伊豆の踊子』同様に、川端康成の旅の出会いから生まれたもので、雪中の火事も実際に起ったことだと川端は語っている。川端は作品内で故意に地名を隠しているが、1934 年（昭和 9 年）6 月 13 日より 1937 年まで新潟県湯沢町の高半旅館（現：高半ホテル）に逗留していたことを随筆『「雪国」の旅』で述べている。

## H2 Heading
### H3 Heading
#### H4 Heading
##### H5 Heading
###### H6 Heading

Custom HTML Markups

2014-06-01T00:00:00-07:00

`.note`, `.store`, and `.download`

A paragraph block with a thin border line.

Usage

[Download](download) it from GitHub
{: .download}

Love this plugin? please consider [buying me a cup of coffee](donate).
{: .store}

Example

Download it from GitHub

Love this plugin? please consider buying me a cup of coffee.

`.largetype`

Make normal paragraph text large enough.

Usage

[PayPal](donate)
{: .largetype}

Example

PayPal

`.browser`

A simple browser frame using pure CSS.

Usage

![Image](https://sparanoid.com/logo.png)
{: .browser}

Example

Lightense Images

A simple library inspired by Tim Holman to view large images up close using simple mouse interaction, and the full screen.

Usage

Add the following setting to your post front-matter field:

plugin: lightense

Markdown markup:

![Image](https://sparanoid.com/photo.jpg)

Lightense Images is activated globally by default, if you want to disable this effect for specific image, you can simply apply .no-lightense CSS class to your image or <img>:

![Image](https://sparanoid.com/logo.png){: .no-lightense}

Please note that if you’re using HTML markup, you should wrap your images into a <p> container.

Example

Image Sizes

There’re different size helpers for images. They’re available using the following CSS classes:

Small Size

![Image](https://sparanoid.com/logo.png){: .size-small}

Medium Size

The medium size is the default size of images, so you don’t need additional CSS classes for it.

![Image](https://sparanoid.com/logo.png)

Large Size

![Image](https://sparanoid.com/logo.png){: .size-large}

Aligned Images

![Image](https://sparanoid.com/logo.png){: .size-left}

![Image](https://sparanoid.com/logo.png){: .size-right}

Aligned images are smaller images beside the text, you can just apply .size-left or .size-right to your images and nothing special markup required. However, that aligned images will be responded to normal large size for small desktops or mobile devices.

Small Images

Useful for images smaller than container width.

![Image](https://sparanoid.com/logo.png){: .no-resize}

Small Images (center)

![Image](https://sparanoid.com/logo.png){: .no-resize.center}

Custom Color Scheme

2014-05-01T00:00:00-07:00

This is an example how to change your post color scheme for specific posts. You can simply add the following variables to your post front-matter field:

scheme-text: "#0029ff"
scheme-link: "#ff00b4"
scheme-hover: "#ff00b4"
scheme-code: "#ad00ff"
scheme-bg: "#00ebff"
scheme-hero-text: "#00ebff"
scheme-hero-link: "#00ebff"
scheme-hero-bg: "#0029ff"

You can also ignore other variables if you only want to change the background:

scheme-bg: "#00ebff"

Unique Post Styling via Custom CSS

2014-04-01T00:00:00-07:00

This is an example how to change your post styling via CSS. You can simply add the css option to your post front-matter field:

scheme-text: "#000"
scheme-link: "#a73300"
scheme-hover: "#ff4e00"
scheme-code: "#a73300"
css: |
  body {
    background-image: linear-gradient(to bottom, #fff500, #ff8f00);
  }

Please note that syntax highlighting may look ugly with the custom background color.

External Link Post

2014-02-01T00:00:00-08:00

This is an example of a Tumblr-like external link post. You can simply add the following setting to your post front-matter field:

link: https://sparanoid.com/

◉ Direct Link to Original Site

Custom Heading Image

2014-02-01T00:00:00-08:00

This is an example of custom post heading image. You can simply add the following setting to your post front-matter field:

heading-img: svg/heading-image.svg
heading-img-local: true
heading-img-width: 400

In Almace Scaffolding v1.1.0, the original svg-headline*, and img-headline* options are deprecated.

heading-img: Heading image filename, if a relative URL (non-external URL) is provided, the file will be prefixed with site.file.
heading-img-local: To avoid relative URL prefixed by site.file, you can set this option to true to prefix it with amsf_user_assets, then you can store your images in _app/assets/.
heading-img-width: Set the width of your heading image. The value will be converted to viewport unit automatically. ie. heading-img-width: 400 will be converted to width: 40vw;

Pro Tips: Keep a <title> tag for your SVG can help Safari generate correct post title for its Reader mode:

<svg xmlns="http://www.w3.org/2000/svg">
<title>Cool Article</title>
…

Custom Heading Background

2014-02-01T00:00:00-08:00

This is an example of custom heading background. You can simply add the following setting to your post front-matter field:

heading-bg: img/heading-background.jpg
heading-bg-local: true
heading-bg-color: "#8141b1"
heading-bg-size: "100px 100px"
heading-bg-position: "center bottom"
heading-bg-repeat: "repeat"
heading-bg-text: "#fff"

heading-bg: Background image filename, if a relative URL (non-external URL) is provided, the file will be prefixed with site.file.
heading-bg-local: To avoid relative URL prefixed by site.file, you can set this option to true to prefix it with amsf_user_assets, then you can store your images in _app/assets/.
heading-bg-color: Background color, recommend setting its value matches your image color tone.
heading-bg-size: Background size, default value is cover.
heading-bg-position: Background position, default value is center center.
heading-bg-repeat: Background repeat, default value is no-repeat.
heading-bg-text: Text color of the heading, set it based on your background image.

Heading image copyright info: © 士郎正宗・Production I.G／講談社・「攻殻機動隊」製作委員会

GitHub Pages Setup Guide

2014-01-01T00:00:00-08:00

The Problem

In short answer: yes, but additional actions required.

tl;dr: You can serve AMSF as a static site on GitHub Pages, but not a Jekyll site using Jekyll renderer provided by GitHub Pages.

There’re some factors that prevent it from generating pages using GitHub Pages renderer:

Many features Almace Scaffolding provides like LiveReload, Sass support, inline SVG, and HTML minification are implemented using Grunt.js, it’s not supported by GitHub Pages.
Almace Scaffolding uses the latest pre-release Jekyll, so not all features are supported by GitHub Pages renderers.
GItHub Pages build server overwrites the source settings. This prevents it from generating pages from current file structure.

The Solution for Users or Organization Sites

Since GitHub Pages for users or organization sites can only be served from the root directory of your master branch. You have to:

Make sure your baseurl is set to "" (empty) in your _config.yml.
Build your site locally (grunt build).
Use your own method, create a script, bash, whatever it works to move the generated pages to the root directory of your repository.
Upload Jekyll generated static files to your username.github.io repository.

If you’d like to keep all things under Git control, you can try the following file structure:

├── _amsf/ (Almace Scaffolding source code)
├── *.html (Jekyll-generated static pages)
└── README.md (your own readme)

You can see this live demo how it actually works.

The Solution for Project Sites

Things can be simpler if you need AMSF for your project sites since GitHub Pages supports serve your site from a subdirectory:

Make the following changes in your _config.yml:
- Change destination to docs
- Change baseurl to the name of your repository slug, ie. /my-project.
- Change flatten_base to true.
Build your site locally (grunt build).
Push changes to GitHub

Contemplating Platforms

How I assembled together a product in my spare time.

Introduction

Focus on the MVP

Lean into the Agile

X Driven Development

Dogfooding

Backlog is important

AI is a friend, not a foe

Compliment workflows with the right tooling

Refactor, refactor, refactor

Automation is the key

A good tool will productise itself

Conclusion

On building resilience with React and Rate-limited APIs

A little React Primer

Hooks and side-effects

Infinite re-renders

What can go wrong

What can be done

Must I use useEffect

In closing

Upgrading Guide from v1 to v2

Upgrading Guide: v1.1.0

Open Graph

Jekyll Theme Compatibility

Introducing Curtana

Features

Deployment Methods

Cloudflare Pages

Web Hosting Providers (FTP/SFTP)

rsync

Amazon S3 (s3_website)

Multiple Themes Support

Welcome

Features

Getting Started

Requirements

Method: Run in Docker

Custom Dependencies

Method: Run Locally

Upgrading

Using Beta Release

Download

Jekyll Migration

Customizing Styles

Configuration

Configuration Settings

Tips

Themes

Overview

Installing Themes

Via Git (GitHub)

Manually Install

Upgrading Themes

Creating Your Own Theme

Overview

AMSF Options

site.name

site.description

site.file

site.twitter

site.force_utf_8

site.robots

Theme Features

(Basic) Multi-Language Support

Smooshing Assets

User Custom Styles Support

User Custom Scripts Support

Page / Post Specific CSS Block Support

Google Analytics Support

Post Published Time

Post Modified Time

Post Reading Time

Publishing Themes

Syntax Highlighting

Markdown Features Test

Indented Code Blocks

Liquid Tag with linenos Support

GFM Code Blocks (fenced_code_blocks)

`site.name`

`site.description`

`site.file`

`site.twitter`

`site.force_utf_8`

`site.robots`

Liquid Tag with `linenos` Support

GFM Code Blocks (`fenced_code_blocks`)

`.note`, `.store`, and `.download`

`.largetype`

`.browser`