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