diff options
Diffstat (limited to 'content/blog/01-hello-world')
| -rw-r--r-- | content/blog/01-hello-world/index.md | 193 | ||||
| -rw-r--r-- | content/blog/01-hello-world/index.org | 190 |
2 files changed, 383 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. |