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
188
189
190
191
192
193
|
#+TITLE: Hello, world!
#+DATE: 2022-08-29
#+AUTHOR: Alexandre Jesus
#+PANDOC_METADATA: slug:hello-world
#+PANDOC_METADATA: updated:2023-08-01
#+PANDOC_EXTENSIONS: commonmark+yaml_metadata_block
#+PANDOC_OPTIONS: standalone:t
#+PANDOC_OPTIONS: shift-heading-level-by:2
#+SPDX-FileCopyrightText: 2022 Alexandre Jesus <https://adbjesus.com>
#+SPDX-License-Identifier: CC-BY-SA-4.0
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. You can find the source code for the website
at https://git.adbjesus.com/adbjesus.com.
* Static Site Generator
Since this site will contain static content, I've decided to go with a
static site generator. In particular, I chose [[https://getzola.org][Zola]]. 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 [[https://github.com/getzola/zola/issues/1787][open
issue]] 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 [[https://orgmode.org][Org]] for writing
content (see this [[https://github.com/getzola/zola/issues/909][issue]]). 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 [[https://orgmode.org/worg/org-contrib/babel/][Org 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 [[https://commonmark.org/][CommonMark]] spec) using [[https://pandoc.org][pandoc]], and the [[https://github.com/emacsorphanage/ox-pandoc][ox-pandoc]]
package for Emacs. To setup ox-pandoc to export =.org= files to
CommonMark I have the following in my Emacs configuration:
#+begin_src elisp :eval no
(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))))
#+end_src
Then, I put the =index.org= for a blog post inside a dedicated folder
for that post:
#+begin_example
content
└── blog
└── 01-hello-world
├── index.org
└── ... // other files
#+end_example
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:
#+begin_src org :eval no
#+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
#+end_src
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.:
#+begin_example
content
└── blog
└── 01-hello-world
├── index.org
├── index.md
└── ... // other files
#+end_example
You can find the Org source for this post [[file:index.org][here]].
* Deploying with Nix
I deploy this site to my [[https://nixos.org][NixOS]] server using the declarative NixOS
configuration capabilities. For this I have a =flake.nix= in the
repository of this site (edit: as of 2023-08-01 the flake no longer
uses flake-utils but the idea is the same, you can check the latest
version on the repository):
#+begin_src 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;
}
);
}
#+end_src
Then I add this repository to the inputs section of the NixOS
=flake.nix= configuration file.
#+begin_src nix
inputs.website = {
url = "git+https://git.adbjesus.com/website";
inputs.nixpkgs.follows = "nixpkgs";
};
#+end_src
and use the =nginx.virtualHosts= option to deploy it:
#+begin_src nix
services.nginx.virtualHosts = {
"adbjesus.com" = {
default = true;
forceSSL = true;
enableACME = true;
locations."/" = {
root = "${website.packages.x86_64-linux.website}/public";
};
};
};
#+end_src
In the future, I will write more about my NixOS configuration using
flakes, which I use to manage my personal computers and server.
* Edits
- 2023-01-08: Updated the link to the website, added note stating that
I no longer use flake-utils.
|
