# Journal CMS **Perfectly Paced Journeys · Content Authoring Tool** A standalone HTML/CSS/JS content management system for writing, managing, and publishing self-contained journal posts directly to a GitHub repository. No server, no framework, no build step — open the file in any browser and connect your repo. --- ## Contents - [Purpose](#purpose) - [Architecture](#architecture) - [Core Engine](#core-engine) - [Niche Packs](#niche-packs) - [Themes](#themes) - [Installation](#installation) - [Step 1 — Create a GitHub Personal Access Token](#step-1--create-a-github-personal-access-token) - [Step 2 — Open the CMS and Connect](#step-2--open-the-cms-and-connect) - [Running the CMS](#running-the-cms) - [Using the Editor](#using-the-editor) - [Creating a Post](#creating-a-post) - [Module System](#module-system) - [Template Picker](#template-picker) - [Publishing](#publishing) - [Images](#images) - [Site Settings](#site-settings) - [Branding](#branding) - [Post Format](#post-format) - [Post Index and build.js](#post-index-and-buildjs) - [Deploying to Cloudflare Pages](#deploying-to-cloudflare-pages) - [Module Reference — Travel Niche](#module-reference--travel-niche) - [Module Reference — Finance Niche](#module-reference--finance-niche) - [Module Reference — Real-Estate Niche](#module-reference--real-estate-niche) - [Module Reference — Legal Niche](#module-reference--legal-niche) - [Troubleshooting](#troubleshooting) --- ## Purpose The Journal CMS is an authoring tool that produces self-contained HTML post files deployable to any static host (Cloudflare Pages, GitHub Pages, Netlify) with no server-side processing required. Each post is a single `.html` file that: - Renders fully without JavaScript - Contains all styles inline (no external CSS dependencies) - Embeds its own metadata as a JSON ` ...hero content... ``` **Round-trip editing:** Opening an existing post in the CMS reads the post file, parses the `post-meta` JSON to restore all metadata, reads the `` markers to reconstruct the module stack, and extracts content from each HTML section back into the form fields. Posts can always be reopened, edited, and re-saved without information loss. Posts are fully self-contained — they render correctly even without the rest of the journal directory. --- ## Post Index and build.js `journal/post-index.json` caches the metadata of every post. It is updated automatically by the CMS on every publish and delete — keeping the sidebar fast without fetching every file from GitHub. If you add, rename, or delete posts outside the CMS (e.g. directly on GitHub), regenerate it by running the build script: ```bash node journal/build.js ``` This also regenerates `journal/index.html` (the public post listing) and `journal/library.html` (the Field Library archive). **Dry run (shows what would be built without writing files):** ```bash node journal/build.js --dry-run ``` --- ## Deploying to Cloudflare Pages 1. Push the project to a GitHub repository. 2. In Cloudflare Pages, create a new project and connect the repository. 3. Set the **build command** to `node journal/build.js`. 4. Set the **publish directory** to `journal`. 5. Deploy. Every time you publish a post via the CMS, a GitHub commit is created, which triggers a Cloudflare Pages deployment automatically. > **If Cloudflare is not redeploying:** check that the CMS branch (set in the Connect screen) matches the production branch in Cloudflare Pages → Settings → Builds & deployments. --- ## Module Reference — Travel Niche | Module | Purpose | |---|---| | `metadata` | Core post fields: title, slug, date, location, excerpt, hero image, category, status, social hashtags | | `hero` | Full-width hero image with overlay text | | `body` | Rich text content block (paragraphs, headings, lists) | | `pullquote` | Large decorative quote with optional attribution | | `midheading` | Section heading with optional subtitle | | `scorecard` | Destination rating grid across 8 dimensions | | `seasons` | Best-times-to-visit grid with month indicators | | `inlineimages` | 1–3 column image gallery with captions | | `personas` | Traveller persona cards (Solo, Couple, Family, Group) | | `companion` | "Read next" companion post link | | `timeline` | Day-by-day itinerary with icons | | `transport` | Transport options table (type, route, cost, duration) | | `eventmetrics` | Key event metrics (dates, venue, attendance, cost range) | | `closing` | Closing paragraph with recap and CTA | | `newslettercta` | Email signup call-to-action | --- ## Module Reference — Finance Niche | Module | Purpose | |---|---| | `metadata` | Core post fields: title, slug, date, excerpt, hero image, category, status, social hashtags | | `hero` | Full-width hero image with overlay text | | `riskrating` | 6-dimension signal grid (Fundamentals, Technicals, Sentiment, Valuation, Macro, Entry Timing) — Bullish / Neutral / Bearish per axis | | `body` | Rich text content block | | `pullquote` | Large decorative quote | | `midheading` | Section heading with optional subtitle | | `tickercard` | Ticker symbol, price, % change, 52W high/low, market cap, sector | | `keymetrics` | Repeatable rows: metric name, value, context/note | | `thesisblock` | Bull case vs Bear case with conviction level and bias tag (Bullish/Neutral/Bearish) | | `tradesetup` | Direction, entry zone, target, stop-loss, thesis summary | | `economevent` | Repeatable economic events: name, date, expected/actual values, market impact badge | | `timeline` | Event or milestone timeline | | `inlineimages` | 1–3 column image gallery with captions | | `closing` | Closing paragraph with recap | | `newslettercta` | Email signup call-to-action | | `disclaimer` | Pre-filled legal not-financial-advice disclaimer block | --- ## Module Reference — Real-Estate Niche | Module | Purpose | |---|---| | `metadata` | Core post fields: title, slug, date, location, content type, author, excerpt, hero image, category, status, social hashtags | | `hero` | Full-width hero image with overlay text | | `market-scorecard` | 8-dimension market rating — Affordability, Inventory, Price Trend, Days on Market, School Quality, Walkability, Investment Potential, Overall Rating (1–5 stars + note per dimension) — singleton | | `property-card` | Address, list/sale price, beds, baths, sq ft, lot size, days on market, MLS number, status badge (Active / Under Contract / Sold / Off Market) — singleton | | `market-metrics` | Repeatable metric rows — Median Sale Price, Days on Market, Price-to-List Ratio, Inventory, and any custom metric | | `price-history` | 1-year, 3-year, 5-year median price milestones rendered as a vertical dot-timeline with % change badges — singleton | | `neighborhood-grid` | Walk Score, Transit Score, Bike Score, Noise Level, Safety Rating, Green Space, Dining & Nightlife, School Quality — each with score bar and note — singleton | | `comparable-sales` | Table of recent comparable sales: address, sale price, sq ft, price/sqft, DOM, date sold | | `investment-thesis` | Cap Rate, Gross Rent Multiplier, Cash-on-Cash Return, Expected Appreciation, Investment Grade — singleton | | `seasonal-timing` | Month-by-month grid: best time to buy, sell, or invest with notes — singleton | | `body` | Lead paragraph and supporting body text with optional inline pull quote | | `pullquote` | Standalone blockquote — a key market insight | | `midheading` | Section heading with optional subtitle | | `timeline` | Chronological event list — neighborhood history or market cycle narrative | | `closing` | Summary and call to action (schedule a showing, book a consultation, download a report) | | `newslettercta` | Email capture block for market report subscribers | --- ## Module Reference — Legal Niche | Module | Purpose | |---|---| | `metadata` | Core post fields: title, slug, date, practice area, content type, author credentials, bar admission, publish date, last updated, social hashtags | | `hero` | Full-width hero image with overlay text | | `regulatory-context` | Governing statute, CFR/USC citation, issuing agency, effective date, jurisdiction scope, amendment history — singleton | | `risk-indicator` | Risk level badge (Critical / High / Medium / Low), risk category (Regulatory / Litigation / Reputational / Operational / Financial), affected parties, timeline to exposure — singleton | | `key-holdings` | Repeatable case blocks: case name, citation, court, date, holding summary, optional dissent | | `compliance-checklist` | Repeatable action items: description, responsible party, deadline (Immediate / 30 days / 90 days / Ongoing), status (Required / Recommended / Optional) — singleton | | `practice-implications` | Structured guidance: practice advice, client counseling, contract updates, filing/disclosure requirements — singleton | | `jurisdiction-matrix` | Table of jurisdictions: jurisdiction name, specific rule, effective date, compliance status (In Effect / Pending / Proposed) — singleton | | `body` | Opening lead and supporting narrative legal analysis | | `pullquote` | Highlighted statutory quote, key holding, or key doctrinal statement | | `midheading` | Section heading — especially important for long compliance briefings | | `timeline` | Chronological sequence: regulatory developments, case history, or compliance deadlines | | `related-authorities` | Repeatable list: related statutes, regulations, or cases with citation and relevance note | | `closing` | Summary of key points and recommended next steps | | `disclaimer` | Attorney advertising compliance disclaimer — **locked**: always present, cannot be removed | | `cle-info` | Accreditation info, credit hours, provider name, course number — for CLE-qualifying content — singleton | > **Locked module:** The `disclaimer` module has `locked: true` in the niche config. The module card renders without a remove button and the text is pre-filled. Bar advertising rules require this to appear on all published legal content. --- ## Troubleshooting ### "GitHub API error 401 — Bad credentials" Your token is invalid, expired, or missing `repo` scope. 1. Go to GitHub → Settings → Developer settings → Personal access tokens. 2. Check if your token has expired. 3. Generate a new token with `repo` scope, then use Disconnect → reconnect. --- ### "GitHub API error 409 — Conflict" The post was modified on GitHub since you last loaded it. This happens with simultaneous sessions. Click the post in the sidebar to reload it fresh, then re-apply changes and publish again. --- ### Sidebar is empty but posts exist in the repo 1. Verify the PAT is valid and has `repo` scope. 2. Verify the Repository field matches `username/repo-name` exactly. 3. Verify the Branch and Posts folder are correct. Open the browser console (F12) to see the specific GitHub API error. --- ### Post doesn't appear on the live site after publishing 1. Go to Cloudflare Pages → your project → Deployments tab. 2. Check if a new deployment was triggered. If not, check the branch setting. 3. If a deployment triggered but failed, check the build logs in Cloudflare. --- ### Modules are missing after re-opening a post Posts edited manually in a text editor may have had the `` markers removed. The CMS requires these markers to reconstruct the module stack. Posts created and saved by the CMS always include them — do not remove them if manually editing a post file. ---