README (5167B)
1 2 dati 3 ==== 4 5 data and template interface 6 7 USAGE 8 ----- 9 10 dati [OPTIONS] 11 12 DESCRIPTION 13 ----------- 14 15 dati aims to provide a universal interface for executing data files, 16 written in any data-serialization language, against template files, 17 written in any templating languages. 18 Ideally dati will support any language you want to use. 19 20 dati works by using various libraries that do all the hard work to 21 parse data and template files passed to it. It generates a data 22 structure of all the passed data files combined (a super-data 23 structure) and executes that structure against a set of root template 24 files. 25 The used libraries are listed below for credit/reference. 26 27 dati can also be imported as a golang package to be used as a library. 28 29 OPTIONS 30 ------- 31 32 - `-r path`, `-root path` = path of template file to execute against. 33 - `-p path...`, `-partial path...`= path of (multiple) template files that are 34 called upon by at least one root template. 35 - If a directory is passed then all files within that directory will 36 (recursively) be loaded. 37 - `-gd path...`, `-global-data path...` = path of (multiple) data files to load 38 as "global data". If a directory is passed then all files within that directory 39 will (recursively) be loaded. 40 - `-d path...`, `-data path...` = path of (multiple) data files to load as 41 "data". If a directory is passed then all files within that directory will 42 (recursively) be loaded. 43 - `-dk name`, `-data-key name` = set the name of the key used for the generated 44 array of data (default: "data") 45 - `-sd attribute`, `-sort-data attribute` = The file attribute to order data 46 files by. If no value is provided, the data will be provided in the order it's 47 loaded. 48 - Accepted values: "filename", "modified". 49 - A suffix can be appended to each value to set the sort order: "-asc" (for 50 ascending), "-desc" (for descending). If not specified, this defaults to 51 "-asc". 52 - `-cfg file`, `-config file` = A data file to provide default values for the 53 above options (see CONFIG). 54 55 CONFIG 56 ------ 57 58 It's possible you'll want to set the same options if you run dati multiple 59 times for the same project. This can be done by creating a file (written as 60 a data file) and passing the filepath to the -cfg argument. 61 62 The key names for the options set in the config file must match the name of 63 the argument option to set (long or short). For example (a config file in 64 toml): 65 66 root="~/templates/blog.mst" 67 partial="~/templates/blog/" 68 gd="./blog.json" 69 data="./posts/" 70 dk="posts" 71 72 DATA 73 ---- 74 75 dati generates a single super-structure of all the data files passed to it. 76 This super-structure is executed against each "root" template. 77 78 The super-structure generated by dati will only have 1 definite key: "data" 79 (or the value of the "data-key" option). This key will overwrite any "global 80 data" keys in the root of the super-structure. Its value will be an array, 81 where each element is the resulting data structure of each parsed "data" 82 file. 83 84 Parsed "global data" will be written to the root of the super-structure and 85 into the root of each "data" array object. If a key within one of these 86 objects conflicts with one of the "global data" keys, then that 87 "global data" key will not be written to the object. 88 89 TEMPLATES 90 --------- 91 92 All "root" template files passed to dati that have a file extension matching 93 one of the supported templating languages will be parsed and executed 94 against the super-structure generated by dati. 95 96 All "parital" templates will be parsed into any "root" templates that have a 97 file extension that match the same templating language. 98 99 SUPPORTED LANGUAGES 100 ------------------- 101 102 Below is a list of the supported data-serialisation languages, used for 103 "data" and "global data" files. 104 105 - JSON (.json), see https://json.org/ 106 - YAML (.yaml), see https://yamllint.com/ 107 - TOML (.toml), see https://toml.io/ 108 109 These are the currently supported templating languages, used for files 110 passed in the "root" and "partial" arguments. 111 112 - mustache (.mu, .mustache), see https://mustache.github.io/ 113 - golang text/template (.tmpl, .gotmpl), see https://golang.org/pkg/text/template/ 114 - golang html/template (.hmpl, .gohmpl), see https://golang.org/pkg/html/template/ 115 - note that this and text/template are almost interchangable, with the 116 exception that html/template will produce "HTML output safe against code 117 injection". 118 - statix (.stx .statix), see https://gist.github.com/plugnburn/c2f7cc3807e8934b179e 119 120 EXAMPLES 121 -------- 122 123 dati -cfg ./dati.cfg -r templates/textfile.mst 124 125 dati -r homepage.hmpl -p head.hmpl -p body.hmpl -gd meta.json -d posts/* 126 127 see the examples/ directory in the dati repository for a cool example. 128 129 LIBRARIES 130 --------- 131 132 As stated above, all of these libraries do the hard work, dati just combines 133 it all together - so thanks to the authors. Also here for reference. 134 135 - The Go standard library is used for parsing JSON, .tmpl/.gotmpl, .hmpl/.gohmpl 136 - github.com/pelletier/go-toml 137 - gopkg.in/yaml.v3 138 - github.com/cbroglie/mustache 139 140 AUTHORS 141 ------- 142 143 - gearsix <gearsix@tuta.io>