overview.md (2765B)
1 # Writing a web site 2 3 ## Structure 4 5 A website consists of a set of *sections* listed in the `menu.tsv` file 6 at the root of the repository. 7 This is a TSV (Tab Separated Value) file in which each line first 8 defines the section label as it will appear in the menu, followed by the 9 targeted content. 10 11 The sections indexed in the menu can be an external http[s] URL, a 12 remote directory managed elsewhere, or, more commonly, a subdirectory of 13 the repository. 14 In this case, this subdirectory must contain an `index.tsv` file that 15 lists the content indexed in the second-level menu. 16 17 As with the `menu.tsv` file, this index is a Tab Separated Value file in 18 which each line first defines the submenu label, followed by its target, 19 i.e. local content (such as an HTML page) or an http[s] URL. 20 This target can be multilingual by using the `@LANG@` macro in its name. 21 It will be replaced by one of the languages listed in the third field of 22 the line. 23 For example, for content available in French and English, the third 24 field will have the value `fr:en`. 25 This last field is only mandatory in the case of multilingual content. 26 Refer to the `examples/index.tsv` file for an example of multilingual 27 indexing. 28 29 ## Content 30 31 The website content is defined by section. 32 Regular pages are written in 33 [Markdown](https://daringfireball.net/projects/markdown/syntax). 34 Each .md file in the section's directory is automatically considered 35 website content and therefore converted to HTML during automatic website 36 generation. 37 38 Shell scripts are also automatically detected as site content. 39 They are supposed to dynamically generate a Markdown file converted to 40 HTML by the build system. 41 The resulting file name is that of the script, with the `.sh` extension 42 simply replaced by `.html`. 43 44 ## Additional Resources 45 46 The other resources in the section can be stored in three subdirectories 47 specific to the section. 48 49 - `images` for storing full-size images; 50 - `thumbs` for storing thumbnails of images, providing a preview while 51 limiting bandwidth and speeding up web page loading; 52 - `downloads` for storing other downloadable content, such as archives, 53 PDFs, etc. 54 55 ## Hooks 56 57 The `hooks` subdirectory of each section contains shell scripts to be 58 executed before the section content is generated. 59 Their names must begin with a two-digit priority number that defines 60 their order of execution, followed by the character '-'. 61 If necessary, they display on standard output the additional files that 62 must be deployed with the rest of the site. 63 64 Hooks can be used, for example, to convert manual pages to HTML, extract 65 the contents of an archive used by section scripts to dynamically 66 generate the content of a web page, etc. 67 It is ultimately a very versatile mechanism that can be used in many 68 ways.