1 files changed, 93 insertions, 0 deletions
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 `<!--TEMPLATE-->`, i.e uppercase HTML comments by convention.
+
+Templates can be organized into folders for your convenience, and are then addressed as `<!--DIR1/DIR2/TEMPLATE-->`
+
+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 `<!--CORE/CONTENT-->` 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 `<!--variable-->`, 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 `<!-- key: value -->`. 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.