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