diff --git a/docs/docs.md b/docs/docs.md
new file mode 100644
index 0000000..8b73591
--- /dev/null
+++ b/docs/docs.md
@@ -0,0 +1,129 @@
+ # PaPy (<span style="color:red">Pa</span>ge with <span style="color:red">Py</span>thon): a Python static site generator
+
+ Using Python3:
+
+ 1. `pip install markdown`
+ 2. Copy contents of /pa-py to local directory.
+ 3. Drop markdown files into /post (see front matter in examples)
+ 4. Generate with `python3 pa.py`.
+ 5. Output is in directory `/public`, complete with RSS and Sitemap.
+
+ `/theme` files can be tweaked to preference.
+
+ ## Features
+
+ - Converts Markdown files to HTML from folder `/post` with support for fenced code blocks, tables, footnotes and smart quotes
+ - Output URLS are clean; i.e. `/post/slug` versus `/post/slug.html`
+ - Front Matter Parsing: Extracts metadata from YAML-style front matter
+ - Template system: Uses HTML template parts (archive.html, footer.html, header.html, head.html, main.html, page.html, single.html, tags.html) from theme directory
+ - Pagination with reverse chronological sorting (newest first)
+ - RSS feed and Sitemap generation
+ - Static asset handling:
+ - Contents of root directory are copied to `/public`
+ - If sub-directories contain markdown files, they too are converted to HTML
+ - `/static` directory for static assets like css and scripts are pushed through
+ - SEO-ready: Can output Open Graph, Twitter card meta and JSON-LD Microdata (optional)
+ - Tags:
+ - Outputs tags from comma-separated front matter: `tags: tag1, tag2`
+ - Outputs tags from on-page hashtag trigger in markdown body `{{ hashtag:example }}`
+ - Front matter tags only are shown at the bottom of the content/blog post
+ - All tags (front matter and on-page hashtag trigger) have `/tags` pages generated and indexed.
+ - Tags support for mixed case hashtags
+ - Date formatting: Displayed dates can be formatted to preference in themes via Python's `strftime()` method.
+
+ ### Content Organisation
+ - Directory Structure:
+ - `post/`: Blog posts (creates `/post/post-name/` URLs)
+ - Other directories: Regular pages (creates `/page-name/` URLs). `/about/` is included by default as an example
+ - `theme/`: main HTML templates
+ - `public/`: Output directory
+ - `static/`: Static files and directories, e.g. `/img`, `/css/main.css`
+
+ ### User Configuration
+
+ **POSTS_PER_PAGE = 10**
+ Number of posts to display per page on index and archive pages.
+
+ **SITE_URL = "https://example.com"**
+ The complete base URL of the site, including protocol (https://).
+
+ **SITE_TITLE = "My Site"**
+ Default site title used in page titles and when no page title is provided.
+
+ **SITE_DESC = "Site Description"**
+ Default site description used in meta tags and when no page description is provided.
+
+ **CONTENT_LANGUAGE = "en"**
+ The language code for the site's content (used in HTML lang attribute).
+
+ **SITE_LOGO = "/img/logo.png"**
+ Absolute URL path to the site's logo image (used in the optional schema.org metadata).
+
+ **THEME = "basic"**
+ The theme to use from the `/themes/` directory. Must match exactly the name of a theme folder.
+
+ **PAGINATION = "numbers"**
+ The options are "numbers" or "direction".
+ This option controls the type of pagination style to output. "numbers" produces a URL chain of page numbers and "direction" is only a "next" & "previous" link.
+
+ **ENABLE_SEARCH = False**
+ The options are "True" or "False".
+ An optional search feature which uses lunr.js. Index is output to root folder as 'search-index.json' for integration.
+
+ **GENERATE_ARCHIVE = "yes"**
+ The options are "yes" or "no"
+ Generates an archive page based on the archive.html template.
+
+ **ARCHIVE_URL = "archive"**
+ The desired URL of the archive output. Someone might prefer '/blog' so here is the place to change it.
+
+ **TAGS_PAGE_TITLE = "tags and categories"**
+ Configurable Tags index page title which can appear on-page and will populate the <title> meta data.
+
+ ### Front Matter
+ **title:** the title which appears in `<title>` meta data and optionally at the top of pages.
+ **summary:** the data which appears in `<meta name="description"` and optionally as a summary of posts on index pages.
+ **description:** alias of summary, as above.
+ **image:** this drives any 'top of post' image (optional).
+ **alt:** the alt-text of the 'top of post' image. If not specified, the default alt-text is 'title:' front matter.
+ **caption:** the caption of the 'top of post' image (optional). Displayed below the image in a `<div class="article-image-caption">`.
+ **tags:** comma-separated post tags, e.g. `tags: tag1, tag2`. These will be passed to the bottom of the post in a tag cloud format.
+ **date:** the date in ISO 8601 standard `YYYY-MM-DD`. Time is optional but recommended to aid correct pagination order.
+
+ Compliant format examples:
+ * Date only:
+ * `2025-09-17`
+
+ * With seconds:
+ * `2025-09-17T14:35:20`
+ * `2025-09-17T14:35:20Z`
+ * `2025-09-17T14:35:20+02:00`
+ * `2025-09-17T14:35:20-05:00`
+
+ * Without seconds:
+ * `2025-09-17T14:35`
+ * `2025-09-17T14:35Z`
+ * `2025-09-17T14:35+02:00`
+ * `2025-09-17T14:35-05:00`
+
+ * Hour only:
+ * `2025-09-17T14`
+ * `2025-09-17T14Z`
+ * `2025-09-17T14+02:00`
+ * `2025-09-17T14-05:00`
+
+ Additionally, fractional seconds (e.g. `.123`) can be added but these are removed during build.
+
+ When no date is provided, the script defaults to the current build time.
+ **Note**: the date/time *will* change at every (re)build, so add a date.
+
+ ### Themes
+
+ Some example themes are included:
+
+ **basic**: A basic theme with all posts displayed as a list on the main index page (newest first).
+ **cards**: Same as basic, with all main index posts laid out as "cards" or "blocks (in `<div>` instead of `<ul>`).
+ **long**: Same as basic, with all main index posts appearing in "long" format on the front page, i.e., the full body of each post is shown.
+
+ The layouts can be remixed to taste - see the example themes for how to do this.
+