From 8233414683d15b55fec1e1cc2e9227acc51ede72 Mon Sep 17 00:00:00 2001 From: Your Name Date: Wed, 8 Jan 2025 01:25:07 +1100 Subject: Version 1.00, initial commit --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..7ff4918 --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# DS-Static + +DS-Static, the Dead Simple Static Website Generator. + + +## Who DS-Static is For + +I had the idea for DS-Static when trying to find a static generator for my website and ran into some problems. + +- I previously used Makesite, but I wasn't in the mood to read and change it's source again. +- I searched other static generators, but disliked their technical complexity, i.e using Node.JS +- Others nad much user complexity, such as Hugo. I wanted a generator that would be more efficient to learn and use, than it would be to hand-write my HTML, assuming I regularly use it. + +Feeling there was nothing that fit the bill, I decided to write my own. I have written two other static site generators in the past but they were too obtuse for others to pick up. I wanted other people to make use of this too. + +I devised a set of goals. + +- Technically uncomplicated, keep LOC low. +- Conceptually simple, quick to start using. +- No requirement to read or modify source code. + +Of these I kept the first two, the third is technically broken but the code modification of the user is minimal, i.e setting some variables and maybe changing the shebang line. + +If you are creating a personal or business website, a blog, a gallery, or some other sort of content-focused website, are familiar with HTML/CSS, and have similar requirements to me, you may find DS-Static useful for yourself. + + +## Installation + +1. If you do not have it already, install **Tcl**. The program was written for Tcl 8.6 and above, but will likely run fine on slightly older versions. +2. Check the shebang line of `main.tcl` points to your Tcl interpreter. On Linux systems this is usually `/bin/tclsh` (the default) but across systems it can differ. Run `whereis tclsh && whereis tcl8.6` to find where yours is located. +3. If you do not have it already, install **pandoc**. + + +## Usage of Program + +### Instructions for Use + +1. Read and modify `config`. + a. `d_source` is the source of content. + b. `d_output` is where generated files are put. + c. `replacement` is a dictionary for simple, global replacements. +2. Write templates in `templates/` directory. Templates are written using Tags; read the next section regarding their use. +3. Populate your `d_source` directory with content. + + +### Warnings and Notes + +- User errors are likely to present as Tcl errors. +- A loop in the template layout will cause a 'waiting' program. +- Files in the output directory will be overwritten. + + +## Tags + +DS-Static's fundamental concept is the tag, which are HTML comments that take on special meaning in this program. There are three types. + +**Templates** are HTML snippets contained in `templates/`. + +**Variables** are 'global' key-value pairs, specified before runtime in the `config` file. + +**Document Variables** are 'local' key-value pairs, specified within a document. + + +### Templates + +Template tags are of the form ``, i.e uppercase HTML comments by convention. + +Templates can be organized into folders for your convenience, and are then addressed as `` + +There are three templates used within the program you must not delete (though you can and should modify) in `templates/core/`. +- `index` is used for generating an index for many files. +- `entry` is used for an entry in the aforementioned index. +- `page` is the default template for a markdown page. + +A reserved template tag is `` which is not an actual file, but is internally used as the placeholder for where post contents may go internally. + +A warning for templates; the program does not check for recursive templates. It is the user's responsibility to write templates in a hierarchical manner. + + +### Variables + +Variable tags are of the form ``, i.e lowercase HTML comments by convention. + +In the file `config.tcl` the user will find a variable named *replacement*, which is a Tcl dictionary. There is documentation explaining how the dictionary works, but I hope it should be straightforward to see. + + +### Document Variables + +Document Variables are of the form ``. The case and whitespace is to the users preference. + +In either a Markdown or a HTML document, the user can include these for certain parameters they wish to configure, such as title, subtitle, author, or other document metadata. + +Two pieces of metadata are automatically generated; *date* which is the last modified date, and *filename* which is the relative address. -- cgit v1.2.3