my-old-man.txt (4879B) [raw]
1 # my-old-man: Adventures in using mdoc(7) as the markup for this site 2 3 _Published: December 30, 2020_ 4 5 *Update:* As of December 2021, I've moved to a 6 [new markup format](/blog/mdoc-to-nihdoc.html). 7 For a glimpse at what the format discussed looks like, here's 8 [the original post](/blog/my-old-man-orig.html). 9 10 Uh oh, 11 looks like, 12 I'm seeing more of my old man(1) in me 13 ~ Mac DeMarco (added (1) by me) 14 15 ## Description 16 17 While Mac wasn't talking about good old roff-style man pages, I 18 felt his words were a fun description of my effort to move from a 19 markdown based templated site to a 20 [`mdoc(7)`](https://man.openbsd.org/mdoc.7) based site. 21 22 After pointing out that 23 [I really did](https://git.sr.ht/~akarle/alexkarle.com/commit/844441fce7ac5c0364b3fe1a217da6889cb937ba) 24 rewrite my site in `mdoc(7)`, you might be wondering why I would do this. 25 This blog post is intended to answer just that. 26 27 ## Why 28 29 ### For the learning experience 30 31 The single biggest motivator of the rewrite was that I like to use 32 this site as a playground for learning new (old) technology, and 33 `mdoc(7)` was on my list of tech to learn. 34 35 What better way to learn a new markup language than to port an 36 existing project to use it? 37 38 I had a blast transferring my old posts and coming up with a new 39 build system. 40 41 ### For the look 42 43 I really enjoy a good [`man(1)`](https://man.openbsd.org/man.1) page. 44 45 You've probably heard it before, but I'll say it again: one of the 46 best parts of using OpenBSD is its concise and comprehensive man 47 pages in the base system. 48 49 There's a certain warm fuzzy feeling when you can learn something 50 both without internet access and with the knowledge that it is the 51 authoritative source. 52 53 I want my site to be a homage to good, well thought out, `man(1)` 54 pages. 55 56 ### Keeping it all in base 57 58 As an OpenBSD nerd, I find a bit of joy in having a site which is 59 built, deployed, and served all via the base OpenBSD system. 60 61 By using [`mandoc(1)`](https://man.openbsd.org/mandoc.1) instead of 62 Markdown.pl, I can now build my site without any additional 63 dependencies. 64 65 Better yet, `mandoc(1)` is ported to the various Linux distros I use 66 day to day, and it is fast. 67 68 ## How 69 70 If you read this far, I thought you might be interested to hear how 71 I'm deploying the content. 72 73 I'm a big fan of automation, so I've rigged up the site to deploy 74 on a push to the master branch. Doing so involved two steps. 75 76 ### Building the mdoc 77 78 I created a small Makefile that builds each HTML file from each man 79 page source. 80 81 The relevant bit is the implicit suffix rule to convert each `.7` 82 file to `.html`: 83 84 SUFFIXES: .7 .html 85 7.html: 86 @echo "mandoc $<" 87 @mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' $< \ 88 | sed 's#</head>#<meta name="viewport" content="width=device-width,initial-scale=1">&# ' \ 89 > $@ 90 91 This looks crazy, but it's not too complex. First, know that `$<` is 92 the source (the `<name>.7` page), and `$@` is the target (the 93 `<name>.html` page). The `@` prefix is a bit of magic to suppress 94 printing the command run (so that all the output shown on git-push 95 is just a single "mandoc" line for each file updated). 96 97 Moving on to the mandoc command, I use the html output of mandoc 98 via `-T,` with the `-O` switch specifying that linked man-page 99 references should look locally first, then to point to 100 man.openbsd.org. This allows me to quickly reference OpenBSD base 101 tools and pages, while also using the terse `.Xr` macro for linking 102 individual site pages. 103 104 Finally, I use a `sed(1)` oneliner to splice in a <meta> viewport tag 105 for mobile devices. 106 107 And that's really it! The rest is just listing the man pages I 108 want built, with a phony default target depending on the html pages 109 so that a `make` builds them all. 110 111 ### Deploying via git hook 112 113 Since I'm self-hosting git on the same server as the website, it's 114 trivial to deploy when it receives a push by leveraging git hooks. 115 116 For the unfamiliar, git hooks are simply shell scripts that are 117 triggered by specific git actions. In this case, I used the 118 post-receive hook to publish after the refs were updated via a `git 119 push`. 120 121 More specifically, I added the following to `<git-dir>/hooks/post-receive:` 122 123 echo "Deploying to to /var/www/htdocs... " 124 WT=/var/www/htdocs 125 git -C ${dir} --work-tree=${WT} checkout -f master 126 make -C ${WT} 127 echo "done" 128 129 So, on any push, it checks out the entire source tree into the 130 webserver's content area and rebuilds only the necessary HTML files 131 (thanks to `make(1)`). 132 133 If I had files I didn't want served, I would modify it to build 134 elsewhere and copy the contents to `/var/www`; however, I'm 135 publishing both the source for the site and the git history at 136 [https://git.alexkarle.com], so I don't see any harm to having the 137 README.md accessible from the root. 138 139 ## See Also 140 141 - [githooks documentation](https://www.git-scm.com/docs/githooks) 142 143 [Back to blog](/blog)