setting up a blog in 11ty

(⌒▽⌒)☆: 7 min. read

Heres a short write up on how I setup my blog with 11ty that is hosted in neocities. So the context for this is that I've always wanted to setup a personal journal of sorts but a variety of factors always prevented me from doing so.

These factors range from where to host, what technology to use?, what content the blog should be about, whether I am experienced enough to actually write articles about technical things^[1]. Naturally these confluence of factors always limited me and I've always pushed back from ever taking the first step. Well, I think I've come to a point in my life that I am confident enough to say that who cares, let me shout into the void just like every other technical writer / blogger in the internet-verse!

So firstly, one of the questions to answer is choose to build the blog from scratch or use a proven solution like wordpress / blogger^[2] etc. Of course, I could just pick one of the vanilla CMS like wordpress, set up an account and then be done with it and focus on the content generation but hey, I am supposed to write software for a living, and besides, it seemed like a fun project to twiddle with so I decided to build from scratch using a static site generator.

Next, is the choice of the static site generator. Choices range from Hugo, Lektor, Gatsby blah blah blah, I chose 11ty^[3] because the name was cool.

Regarding the choice of the hosting service, I am a really cheap person, I have not gotten to the stage of purchasing a domain and paying a maintenance fee monthly. I sort of stumbled upon neocities and it brought back memories of geocities and those innocent days of exploring the internet so I decided on it. The neocities website has some cool projects that one should check out if one has the time. Plus the free plan allows for 1GB of storage which should be enough for text based entries, I'll probably find a way to solve the storage issues in the future next time.

Next was to decide on the features that this particular blog should have, I think the first post has highlighted the individual features that I can write in a markdown file^[4]. But to make it easier for the reader, I will go through the expectations for what I wanted to be able to be written in a markdown file, and how I managed to achieve them.

1. should not care so much about the css, maybe only the font.^[5]
2. should be able to have syntax highlighting in a code-block
3. should be able to have responsive images
4. should be able to embed social media (twitter tweets, youtube videos) easily.
5. should be able to parse and display latex in a easy way.
6. should be able to easily deploy to neocites when I push a branch into master

should not care so much about the css

Even though my background is in front-end, but as I get more experienced in the software field, I really abhor handling css and css-related things, especially responsiveness. This is really the grumpy old man in me just complaining. I'll admit that I may not be able to reach the levels of comfort when I'm dealing with css, so kudos to the people who like and work with css everyday to make the internet a brighter place. Since I really do not want to handle css, thus this 'css framework' is perfect for me. I don't think I really need explaining on how I set up new.css in the project as the steps are relatively simple, once we link the cdn to the site, all semantic html tags will be then styled according to the opinions of new.css creators.

<nav>
  <a href="...">/</a>
  <a href="...">/about</a>
  <a href="...">/archive</a>
  <a href="...">/portfolio</a>
</nav>

would render something like the nav bar located above.

While there is room for customisation, I think going too far into customisation will defeat the purpose of not handling css. The only 'customisation' I did was to add a global google font for myself, I really like this Anonymous Pro font, I use it everywhere.

should be able to have syntax highlighting in a code-block

The markdown parser that 11ty uses is markdown-it, and this particular package does not support syntax highlighting which is a bummmer because syntax highlights make code more readable. Enter @11ty/eleventy-plugin-syntaxhighlight, which is an official plugin by 11ty, follow the instructions written on the installation page and one would get syntax highlighting enabled.

const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight);
  ...
};

don't forget to add a prismJS theme css for the code block styling, I am using vs-prism theme, just search for prismJS css themes to find out your favorite theme.

should be able to have responsive images

for responsive images, other people have written up an extensive article and I'm being lazy now so I'll just make a link to the guy's .dev page. In the near future, I would like to refactor his code as I feel that its far too repetitive for my liking. That requires some thought and consideration which I am not in the mood of currently, so his quick and dirty solution is fine for now.

should be able to embed social media (twitter tweets, youtube videos) easily.

for this condition, I just wanted to be able to embed things like tweets and youtube videos easily from just a bare link.

enter these other plugins eleventy-plugin-embed-twitter and eleventy-plugin-youtube-embed, which help fulfil that requirement. The performance for these plugins are less than ideal (blank content before popping in) but I honestly don't expect embedding many social media things in my blog entries, so I am fine with them in the meanwhile. I am sure in the long run, some optimisations could be done but I don't really care at this point in time.

should be able to parse and display latex in a easy way.

so out of the box, markdown-it does not come with LaTeX integration, so markdown-it-katex package comes to the rescue. Most websites that render Latex usually use Mathjax but Katex seems faster?? so I decided to use it.

To install this, I highly suggest reading my .eleventy.js config in the blog's repo, it might not be commented but I think its readable enough.

Once installed, one can then write nice inlined math like this $e^{i\Theta}=cos\Theta+i\ sin\Theta$, and blocked ones like:

$x^2+y^2=z^2$

should be able to easily deploy to neocites when I push a branch into master

last but not least, for the repo that contains all the source code for this blog, I added github actions to setup a simple CI/CD flow for it. Now, when I push a branch into master, my changes are propagated and will be built and published. Heres the config for this particular workflow:

name: Deploy to neocities

# only run on changes to master
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      # Set up any tools and build steps here
      # This example uses a Node.js toolchain to build a site
      - name: Use Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install deps and build
        run: |
          npm i
          npm run build
      # When the dist_dir is ready, deploy it to neocities
      - name: Deploy to neocities
        uses: bcomnes/deploy-to-neocities@v1
        with:
          api_token: $
          cleanup: false
          dist_dir: _site

in fact I just copied wholesale the instructions that was provided by the github workflow creator. Note that one needs to set up a secret with the neocities api token which has to be obtained from neocities settings page.

Whew, that was a long writeup, I hope that whoever stumbles upon this post gets the information required. Until then, I'll write another post whenever I have a topic to discuss.