diff --git a/docs/content-organisation.md b/docs/content-organisation.md
new file mode 100644
index 0000000..198b783
--- /dev/null
+++ b/docs/content-organisation.md
@@ -0,0 +1,8 @@
+ ## 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`
+
diff --git a/docs/docs.md b/docs/user-configuration.md
similarity index 53%
rename from docs/docs.md
rename to docs/user-configuration.md
index 8b73591..93ec960 100644
--- a/docs/docs.md
+++ b/docs/user-configuration.md
@@ -1,45 +1,4 @@
- # 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
+ ## User Configuration
**POSTS_PER_PAGE = 10**
Number of posts to display per page on index and archive pages.
@@ -80,7 +39,8 @@ The desired URL of the archive output. Someone might prefer '/blog' so here is t
**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
+ ## 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.
@@ -117,13 +77,3 @@ Additionally, fractional seconds (e.g. `.123`) can be added but these are remove
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.
-