Initial site, and first blog post

3 files changed, 389 insertions, 0 deletions

diff --git a/content/blog/01-hello-world/index.md b/content/blog/01-hello-world/index.md
new file mode 100644
index 0000000..e0aaefe
--- /dev/null
+++ b/content/blog/01-hello-world/index.md
@@ -0,0 +1,193 @@
+---
+author: A.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
+nginx.virtualHosts = {
+  "adbjesus.com" = {
+    default = true;
+    forceSSL = true;
+    enableACME = true;
+    locations = {
+      "/" = {
+        root = "${inputs.website.packages.${system}.website}/public";
+        extraConfig = ''
+          add_header Last-Modified "${toDateTime inputs.website.lastModified}";
+          add_header Cache-Control max-age="${toString (60 * 60 * 24)}";
+        '';
+      };
+    };
+  };
+};
+```
+
+In the future, I will write more about my NixOS configuration using
+flakes, which I use to manage my personal computers and server.
diff --git a/content/blog/01-hello-world/index.org b/content/blog/01-hello-world/index.org
new file mode 100644
index 0000000..aa51773
--- /dev/null
+++ b/content/blog/01-hello-world/index.org
@@ -0,0 +1,190 @@
+#+TITLE: Hello, world!
+#+DATE: 2022-08-29
+#+AUTHOR: A.D.B. Jesus
+#+PANDOC_METADATA: slug:hello-world
+#+PANDOC_EXTENSIONS: commonmark+yaml_metadata_block
+#+PANDOC_OPTIONS: standalone:t
+#+PANDOC_OPTIONS: shift-heading-level-by:2
+#+SPDX-FileCopyrightText: 2022 A.D.B. 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. 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 [[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:
+
+#+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
+nginx.virtualHosts = {
+  "adbjesus.com" = {
+    default = true;
+    forceSSL = true;
+    enableACME = true;
+    locations = {
+      "/" = {
+        root = "${inputs.website.packages.${system}.website}/public";
+        extraConfig = ''
+          add_header Last-Modified "${toDateTime inputs.website.lastModified}";
+          add_header Cache-Control max-age="${toString (60 * 60 * 24)}";
+        '';
+      };
+    };
+  };
+};
+#+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.
diff --git a/content/blog/_index.md b/content/blog/_index.md
new file mode 100644
index 0000000..e6aaf2f
--- /dev/null
+++ b/content/blog/_index.md
@@ -0,0 +1,6 @@
++++
+title = "Blog"
+sorted_by = "date"
+template = "blog.html"
+generate_feed = true
++++