1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
---
author: Alexandre D. B. Jesus
date: 2022-08-29
slug: hello-world
title: Hello, world!
---
I have been thinking of starting a blog for a while, mostly to write
about stuff that makes no sense to publish academically, but also to
improve my writing skills. I expect to mostly write about Programming,
Emacs, Linux, and other tech topics. But we will see where it goes.
In this first post I will quickly go over the implementation and
deployment of this site. Note that, you can find the code for this site
at <https://git.adbjesus.com/website>.
### Static Site Generator
Since this site will contain static content, I've decided to go with a
static site generator. In particular, I chose
[Zola](https://getzola.org). The main reason for using Zola and not
something else is that I am familiar with its implementation language
(Rust). This can allow me to easily contribute to the project to fix any
issue or scratch any itch.
In terms of styling, I'm using simple templates and CSS I implemented
myself, which match the light/dark system theme option set by the user.
Something I am not yet doing, is using syntax highlighting for code in
blog posts. Although Zola supports this, it does not support some of the
languages that I want, such as Emacs Lisp and Nix, and it is using old
and buggy Sublime syntaxes. There is currently an [open
issue](https://github.com/getzola/zola/issues/1787) to replace the
current system. Another option, would be to use a javascript based
syntax highlighter. However, I would rather keep my site
javascript-free. As a result, since I don't consider it to be a critical
feature for now, I will not implement any syntax highlighting for the
time being.
### Using Org
One issue I had with Zola is that it does not suppor
[Org](https://orgmode.org) for writing content (see this
[issue](https://github.com/getzola/zola/issues/909)). However, I would
prefer to use it instead of markdown because I prefer and am more
comfortable with its syntax, but also because I want to be able to use
[Org Babel](https://orgmode.org/worg/org-contrib/babel/) to execute code
within the `.org` file directly when writing posts for which executing
code is useful.
Nonetheless, this proved not to be an issue for my simple use case
because I can automatically convert `.org` files to `.md` files
(following the [CommonMark](https://commonmark.org/) spec) using
[pandoc](https://pandoc.org), and the
[ox-pandoc](https://github.com/emacsorphanage/ox-pandoc) package for
Emacs. To setup ox-pandoc to export `.org` files to CommonMark I have
the following in my Emacs configuration:
``` elisp
(use-package ox-pandoc
:ensure t
:after org
:custom
(org-pandoc-menu-entry
'((?c "to cmk." org-pandoc-export-to-commonmark)
(?C "to cmk and open." org-pandoc-export-to-commonmark-and-open))))
```
Then, I put the `index.org` for a blog post inside a dedicated folder
for that post:
``` example
content
└── blog
└── 01-hello-world
├── index.org
└── ... // other files
```
The `index.org` file includes some metadata in its header for both Zola
and ox-pandoc. For example, for this post I'm using the following
header:
``` org
#+TITLE: Hello, world!
#+DATE: 2022-08-25
#+PANDOC_METADATA: slug:hello-world
#+PANDOC_EXTENSIONS: commonmark+yaml_metadata_block
#+PANDOC_OPTIONS: standalone:t
#+PANDOC_OPTIONS: shift-heading-level-by:2
```
The `TITLE`, `DATE`, and `PANDOC_METADATA` fields are added to the
exported markdown metadata block. To add the metadata block to the
generated markdown file we set the `yaml_metadata_block` pandoc
extension in `PANDOC_EXTENSIONS`, and the `standalone:t` option in
`PANDOC_OPTIONS`. The last line is used to start the generated headings'
levels at 3 for styling purposes.
Finally, I use the `C-c C-e p c` shortcut to generate the markdown file,
which goes into the same folder, i.e.:
``` example
content
└── blog
└── 01-hello-world
├── index.org
├── index.md
└── ... // other files
```
You can find the Org source for this post [here](index.org).
### Deploying with Nix
I deploy this site to my [NixOS](https://nixos.org) server using the
declarative NixOS configuration capabilities. For this I have a
`flake.nix` in the repository of this site:
``` nix
{
description = "My personal website";
inputs = {
nixpkgs = {
url = "github:nixos/nixpkgs/nixos-22.05";
};
flake-utils = {
url = "github:numtide/flake-utils";
inputs.nixpkgs.follows = "nixpkgs";
};
};
outputs = { self, nixpkgs, flake-utils }:
flake-utils.lib.eachDefaultSystem (system:
let
pkgs = import nixpkgs { inherit system; };
in rec {
packages.website =
pkgs.stdenv.mkDerivation {
name = "website";
src = self;
buildInputs = [ pkgs.zola ];
buildPhase = ''
zola build
'';
installPhase = ''
mkdir -p $out cp -Tr public $out/public
'';
};
packages.default = self.packages.${system}.website;
}
);
}
```
Then I add this repository to the inputs section of the NixOS
`flake.nix` configuration file.
``` nix
inputs.website = {
url = "git+https://git.adbjesus.com/website";
inputs.nixpkgs.follows = "nixpkgs";
};
```
and use the `nginx.virtualHosts` option to deploy it:
``` nix
services.nginx.virtualHosts = {
"adbjesus.com" = {
default = true;
forceSSL = true;
enableACME = true;
locations."/" = {
root = "${website.packages.x86_64-linux.website}/public";
};
};
};
```
In the future, I will write more about my NixOS configuration using
flakes, which I use to manage my personal computers and server.
|
