star-typesetting.7 (15944B)
1 .\" Copyright (C) 2017, 2025 |Méso|Star> (contact@meso-star.com) 2 .\" 3 .\" This program is free software: you can redistribute it and/or modify 4 .\" it under the terms of the GNU General Public License as published by 5 .\" the Free Software Foundation, either version 3 of the License, or 6 .\" (at your option) any later version. 7 .\" 8 .\" This program is distributed in the hope that it will be useful, 9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 .\" GNU General Public License for more details. 12 .\" 13 .\" You should have received a copy of the GNU General Public License 14 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 15 .Dd December 4, 2025 16 .Dt STAR-TYPESETTING 7 17 .Os 18 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 19 .Sh NAME 20 .Nm star-typesetting 21 .Nd generate static content for online publication 22 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 23 .Sh DESCRIPTION 24 .Nm 25 is a toolchain that automates the creation of online publications 26 and aims for simplicity and portability. 27 First, by using Markdown syntax for author content, a simple, 28 lightweight, human-readable markup language that offers only minimal 29 formatting of text and images. 30 Second, thanks to its generated content, which is pure HTML laid out by 31 a single CSS file. 32 And finally, thanks to the tools it relies on, based on well-established 33 standards such as POSIX shell and POSIX make. 34 All this with the goal of helping authors focus solely on the content 35 they want to write, rather than on layout, the generation process, 36 tool-related tricks, or long-term portability issues. 37 .Pp 38 Behind its apparent rigidity and simple appearance, 39 .Nm 40 offers great flexibility to authors who wish to go beyond simply 41 publishing handwritten texts with default style. 42 The Markdown syntax supports inline HTML for those who find its syntax 43 alone too restrictive. 44 It is also possible to write shell scripts that dynamically generate 45 content when creating the website, for example to compose a page from 46 external resources or to generate a list of downloadable archives from 47 published files. 48 Finally, 49 .Nm 50 offers a system of hooks, i.e., shell scripts executed before content 51 generation, for example, to sign files offered for download or retrieve 52 external content used to dynamically generate a web page. 53 Hooks are ultimately a very versatile mechanism that can be used in many 54 ways, far beyond those for which they were originally designed. 55 .Pp 56 This reference documentation describes the structure of a website as 57 managed by 58 .Nm , 59 the syntax of the files used to describe its navigation menu, and the 60 toolchain it relies on to generate and publish a website. 61 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 62 .Sh CONTENT STRUCTURE 63 A well-formed 64 .Nm 65 content consists of a set of directories, called 66 .Em sections , 67 in which the section content is stored. 68 .Pp 69 The section directories are referenced in the mandatory 70 .Pa menu.tsv 71 file located at the root of the 72 .Nm 73 content, called the 74 .Em working directory . 75 The content indexed in each section is listed in the section's 76 .Pa index.tsv 77 file, also required by 78 .Nm . 79 .Pp 80 The 81 .Pa menu.tsv 82 file and the 83 .Pa index.tsv 84 files for each section are used by 85 .Nm 86 to generate the site's navigation menu. 87 The first level of the menu lists the labels of the sections referenced in 88 .Pa menu.tsv . 89 The second level of the menu lists the content indexed in the section 90 selected in the first level, as listed in its 91 .Pa index.tsv 92 file. 93 .Pp 94 The order of the labels in the first or second level menu follows the 95 order of the entries in the 96 .Pa menu.tsv 97 and 98 .Pa index.tsv 99 files. 100 .\""""""""""""""""""""""""""""" 101 .Ss Section content 102 Each section must have an 103 .Pa index.tsv 104 file that lists the contents of the section indexed by the navigation 105 menu. 106 .Pp 107 A section must also store the sources of its content, written in 108 Markdown syntax and suffixed by the 109 .Dq .md 110 extension to be automatically detected, then processed and converted to 111 HTML by 112 .Nm . 113 The file it generates has the same name as its Markdown sources, 114 except that the 115 .Dq .md 116 extension is replaced by 117 .Dq .html . 118 .Pp 119 Files with the 120 .Dq .sh 121 extension in the root directory of a section are considered shell 122 scripts intended to dynamically generate the Markdown sources of web 123 pages. 124 .Nm 125 executes them and redirects their standard output to intermediate 126 Markdown files named after their script, with the 127 .Dq .sh 128 extension replaced by 129 .Dq .md . 130 These files are then processed by 131 .Nm 132 as normal Markdown sources, i.e., converted to HTML files as described 133 above. 134 .Pp 135 In principle, the root of a section should contain a Markdown file 136 .Pq or a shell script 137 corresponding to each entry in the 138 .Pa index.tsv 139 file. 140 However, there may be more than this, as several pages may not be 141 directly accessible from the menu; 142 several of them may only be referenced by other pages. 143 .Pp 144 Finally, four subdirectories have significance for 145 .Nm 146 when they are 147 present in a section: 148 .Bl -tag -width Ds 149 .It Pa downloads 150 is supposed to store downloadable content for the section, such as 151 archives, PDFs, etc. 152 .It Pa hooks 153 stores scripts to be executed by 154 .Nm 155 before generating the section's 156 content. 157 Refer to the section of the manual devoted to hooks for a complete 158 description. 159 .It Pa images 160 is intended to store full-size images. 161 .It Pa thumbs 162 store thumbnails of images stored in the images directory. 163 Authors should use these thumbnails to provide a preview of the images 164 and thus limit the bandwidth required to display a page. 165 They can then provide a link to the full-resolution image for those who 166 wish to access it. 167 .El 168 .Pp 169 With the notable exception of the 170 .Pa hooks 171 subdirectory 172 .Po see 173 .Sx HOOKS 174 section 175 .Pc , 176 the other subdirectories are taken as is by 177 .Nm , 178 which publishes them with their complete content when deploying the 179 website. 180 In other words, these are simply directories used to semantically 181 describe the content they store, automatically copied when the website 182 is deployed. 183 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 184 .Sh MENU.TSV 185 The 186 .Nm 187 file is mandatory for 188 .Nm . 189 It must be located at the root of the working directory. 190 In fact, it is the presence of this file that defines a directory as the 191 working directory for 192 .Nm . 193 .Pp 194 This file defines the top-level entries of the navigation menu, in the 195 order in which they are listed there. 196 It is a simple text file where each line is formatted into two fields 197 separated by a tab, namely: 198 .Bl -enum -offset Ds 199 .It 200 the 201 .Em label , 202 i.e., the name of the entry as it appears in the navigation 203 menu. 204 .It 205 the 206 .Em content 207 targeted by the label. 208 This may include: 209 .Bl -dash -compact 210 .It 211 a local subdirectory, i.e. a section directory containing an 212 .Pa index.tsv 213 file 214 .Po 215 see the 216 .Sx INDEX.TSV 217 section 218 .Pc , 219 .It 220 a remote directory that remains relative to the current working 221 directory once installed, but managed elsewhere, 222 .It 223 an http[s] URL. 224 .El 225 .El 226 .Pp 227 Empty lines are ignored, as are comments, i.e., text after the hash 228 character 229 .Pq # . 230 .\""""""""""""""""""""""""""""" 231 .Ss Example 232 Below is an example of a 233 .Pa menu.tsv 234 file that defines four entries: two targeting sections, one external 235 URL, and the last one a remote directory, local to the working tree 236 once deployed, but managed elsewhere. 237 .Bd -literal -offset Ds 238 # Regular sections 239 About my_section 240 Doc man_pages 241 242 # External link to the content license 243 License http://creativecommons.org/licenses/by-nd/4.0/ 244 245 # Web interface for git repositories 246 Git git 247 .Ed 248 .Pp 249 Note that there is no difference between normal sections and the git 250 entry, except that the latter targets a directory that is not local to 251 the working tree before it is deployed to the remote server. 252 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 253 .Sh INDEX.TSV 254 Each section, i.e., each local subdirectory referenced in the 255 .Pa menu.tsv 256 file, must contain an 257 .Pa index.tsv 258 file. 259 It defines the second-level entries in the navigation menu, i.e., the 260 content indexed in the section selected in the first-level menu. 261 .Pp 262 This file is formatted as a set of three values separated by tabs, which 263 are in the following order: 264 .Bl -enum -offset Ds 265 .It 266 the 267 .Em label 268 of the indexed content, as it appears in the navigation menu. 269 .It 270 the 271 .Em content 272 indexed by the label, which can be an HTML page related to 273 the section or an http[s] URL. 274 This content can be multilingual by using the 275 .Dq @LANG@ 276 macro in its name. 277 This macro will be replaced by one of the languages listed in the third 278 field of the line, namely: 279 .It 280 a 281 .Em list of languages 282 in which the indexed content is available. 283 This is mandatory only for multilingual content. 284 Each entry in the list, separated from the previous one by a colon 285 .Pq \&: 286 defines one of the possible values of the 287 .Dq @LANG@ 288 macro in the content name. 289 The available languages appear in the second-level menu in the order in 290 which they are listed. 291 The first language in the list is the default language used when 292 multilingual content is selected via the menu. 293 .El 294 .Pp 295 Empty lines are ignored, as are comments, i.e., text after the hash 296 character 297 .Pq # . 298 .\""""""""""""""""""""""""""""" 299 .Ss Example 300 Here is an example of an 301 .Pa index.tsv 302 file indexing three content items: 303 the first is a standard page; 304 the second is multilingual content provided in English and French. 305 Both pages have the same name, except for the suffix indicating their 306 language, namely 307 .Pa legal-en.html 308 and 309 .Pa legal-fr.html ; 310 the third and final link redirects to an https URL. 311 .Bd -literal -offset Ds 312 # Regular content 313 Home about.html 314 315 # Multilingual content 316 Legal notice legal-@LANG@.html en:fr 317 318 # External link 319 Super Dimension Fortress https://sdf.org/ 320 .Ed 321 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 322 .Sh HOOKS 323 Each section indexed by the 324 .Pa menu.tsv 325 file can contain a 326 .Pa hooks 327 subdirectory. 328 This subdirectory should contain shell scripts to be executed before 329 generating the section content. 330 .Pp 331 It may seem strange to use hooks when shell scripts can already be used 332 to generate dynamic content 333 .Po 334 see 335 .Sx Section content 336 .Pc . 337 However, this mechanism alone not only fails to properly separate the 338 different tasks, but also remains limited. 339 An automatic generation script is associated with a web page, so any 340 additional content it might generate would not be tracked by the build 341 system, which would therefore be unable to deploy it. 342 Furthermore, there is no way to prioritize the execution of the various 343 generation scripts, which are, by design, independent of each other. 344 Hence kook scripts, which are much more versatile than generation 345 scripts. 346 .Pp 347 The name of a hook script must begin with a two-digit prefix followed by 348 a dash 349 .Pq - , 350 and end with the extension 351 .Dq .sh . 352 The two-digit prefix is used to prioritize the execution of hooks: the 353 smaller the number, the higher the priority. 354 Thus, hook scripts with the prefix 355 .Dq 00 356 will be executed first, while those with the prefix 357 .Dq 99 358 will be executed last. 359 .Pp 360 On output, a hook script must write the paths to the files it has 361 generated and which must be deployed with the website. 362 These paths must be relative to the working directory 363 .Po 364 i.e., the 365 directory of the 366 .Pa menu.tsv 367 file 368 .Pc , 369 and not to the directory of the section to which the hook script 370 belongs. 371 Each line of the output must contain only one path, so that the number 372 of lines written corresponds to the number of files generated by the 373 hook that must be deployed. 374 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 375 .Sh BUILD SYSTEM 376 The 377 .Nm 378 conductor is a POSIX makefile consisting of a few lines that automates 379 the generation of the website. 380 Assuming 381 .Nm 382 has been installed in 383 .Pa /usr/local 384 .Pq default behavior , 385 the user can retrieve this makefile from the 386 .Pa /usr/local/share/star-ty 387 directory, along with its 388 .Pa config.mk 389 file, which controls the behavior of the makefile using a set of macros. 390 .Pp 391 The macros defined in 392 .Pa config.mk 393 are as follows: 394 .Bl -tag -width Ds 395 .It Va PREFIX 396 Destination URL where content is deployed with 397 .Xr rsync 1 . 398 The supported URL syntax is therefore that of rsync. 399 By default, this is a dummy URL that the user must update, presumably 400 with a remote directory served by an http[s] server. 401 .It Va MD2HTML 402 Tool used to convert Markdown sources to HTML. 403 The default value is 404 .Xr md2html 1 . 405 .It Va GROUP 406 Group to which the website content belongs once deployed on 407 .Va PREFIX . 408 The group is used to give write access to all members who belong to it. 409 This means that different users can update the website, provided they 410 belong to 411 .Va GROUP . 412 .It Va RESOURCES 413 List of additional resources to be deployed on 414 .Va PREFIX , 415 which are not already managed by 416 .Nm . 417 .El 418 .Pp 419 The makefile targets are as follows: 420 .Bl -tag -width Ds 421 .It Cm build 422 Generate the whole website. 423 This is the default target, i.e., the one runs when running 424 .Xr make 1 425 without any argument. 426 .It Cm clean 427 Delete generated content such as HTML pages, dynamically generated 428 intermediate Markdown files, or temporary files used internally by 429 .Nm . 430 .Pp 431 It is recommended to run the 432 .Cm clean 433 target before a 434 .Cm build , 435 to ensure that all content is regenerated, thus taking into 436 account all the latest updates. 437 Indeed, while source updates can be managed automatically, this 438 is not the case for intermediate files, which are managed by user 439 scripts. 440 .Pp 441 Note that not all intermediate content is necessarily deleted 442 if it is not directly managed by 443 .Nm , 444 such as temporary content generated by hook scripts 445 .Po 446 see the 447 .Sx HOOKS 448 section 449 .Pc . 450 .It Cm lint 451 Use 452 .Xr tidy 1 453 to verify that the generated HTML pages are well-formed, and 454 .Xr shellcheck 1 455 to verify the accuracy of shell scripts, whether they are used to 456 generate dynamic content or by hooks. 457 Both tools must therefore be available. 458 .It Cm install 459 Copy the generated website to the URL defined by the 460 .Va PREFIX 461 macro. 462 .El 463 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 464 .Sh CASCADING STYLE SHEETS 465 Each HTML page generated by 466 .Nm 467 searches for a CSS file named 468 .Pa sty.css 469 at the root of the working directory. 470 Like the build system files, a template for this style sheet can be 471 retrieved from the example installed with 472 .Nm , 473 which is installed by default in 474 .Pa /usr/local/share/star-ty . 475 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 476 .Sh EXAMPLES 477 .Nm 478 is installed with an example that not only provides the compilation 479 system files and a style sheet, but also illustrates how to write 480 content in 481 .Nm . 482 .Pp 483 Assuming 484 .Nm 485 is installed in 486 .Pa /usr/local 487 .Pq default behavior , 488 start by copying it locally. 489 It will be the working directory: 490 .Bd -literal -offset Ds 491 cp -r /usr/local/share/star-ty my_web_site 492 cd my_web_site 493 .Ed 494 .Pp 495 Run make to generate the content: 496 .Bd -literal -offset Ds 497 make 498 .Ed 499 .Pp 500 The resulting website can be viewed locally, either in the working 501 directory itself: 502 .Bd -literal -offset Ds 503 "${BROWSER:-lynx}" ./home/about.html 504 .Ed 505 .Pp 506 or deployed to a temporary directory: 507 .Bd -literal -offset Ds 508 tmp="${TMPDIR:-/tmp}/www" 509 make PREFIX="${tmp}" GROUP="$(id -gn)" install 510 "${BROWSER:-lynx}" "${tmp}/home/about.html" 511 .Ed 512 .Pp 513 Modify the content as needed, then, once finished, publish the website 514 by deploying its content to a remote machine that publicly serves its 515 local 516 .Pa /srv/www 517 directory via an http[s] server. 518 Allow members of the 519 .Dq www 520 group to update deployed files: 521 .Bd -literal -offset Ds 522 make clean 523 make PREFIX=remote:/srv/www GROUP=www install 524 .Ed 525 .Pp 526 Note the 527 .Dq make clean 528 directive used to force complete regeneration of the content on 529 .Dq make install 530 to ensure that it is up to date with the latest changes. 531 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 532 .Sh SEE ALSO 533 .Xr make 1 , 534 .Xr rsync 1 , 535 .Xr sty-genhead 1 , 536 .Xr sty-hooks 1 , 537 .Xr sty-index 1 , 538 .Xr sty-list 1