Initial site, and first blog post

1 files changed, 190 insertions, 0 deletions

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.