star-ty

Generate content for online publication
git clone git://git.meso-star.com/star-ty.git
Log | Files | Refs | README | LICENSE

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