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