Return to Consciousness

A Jekyll site hosting 26 philosophical essays exploring consciousness-first metaphysics (analytic idealism).

Site: https://returntoconsciousness.org/

Project Structure

  • Root .md files (e.g., rtc.md, apc.md) — individual essays with YAML front matter (layout, title, subtitle, description)
  • index.md — project homepage with essay listing, DOIs, and section structure
  • readers-guide.md — reading guide with recommended paths
  • _layouts/default.html — site layout with navigation menu
  • assets/css/style.scss — site styling
  • exports/pdf/ — generated PDF files for each essay
  • exports/pdf-checksums — SHA256 checksums from last Zenodo upload
  • _draft/ — draft/working files

Essays (26 total)

Ordered by index.md sections:

Section Essays
Methodological Foundation ibc
Foundational Synthesis rtc
Structural Extensions apc, bse, ost, bio, cac, cua, poa
Epistemic Gatekeepers mmn, eop, amr, wes, tgq, wpc, fpa, eaa, raw
Applied Domains ela, tin, aam, cst, sac, eth
Boundary Tests tcj, tes

Draft & Noindex Pages

Several root .md files are marked noindex: true (excluded from search engines via <meta name="robots">):

  • noindex.md — landing page listing all noindex pages
  • exports/report.md — analysis score report

The _draft/ directory contains working files (notes, templates, task lists) that are not published.

Scripts

All scripts are in scripts/. Most require bash and assume macOS.

generate-pdfs.sh

Converts essay .md files to PDF using pandoc + xelatex.

./scripts/generate-pdfs.sh           # only regenerate if source is newer
./scripts/generate-pdfs.sh --force   # regenerate all

Requires: pandoc, xelatex (via basictex or mactex)

Outputs to exports/pdf/. Extracts title/subtitle from YAML front matter, strips Jekyll templating, and produces A4 PDFs with Times New Roman.

generate-complete.py

Concatenates all 26 essays into a single PDF and a single Markdown file, ordered by index.md sections.

python3 scripts/generate-complete.py
python3 scripts/generate-complete.py --output-pdf path/to/output.pdf
python3 scripts/generate-complete.py --output-md path/to/output.md

Requires: pdfunite (from poppler; install via brew install poppler) for PDF generation

Default outputs: exports/rtc-complete.pdf and rtc-complete.md (project root)

zenodo.py

Unified Zenodo script. Handles all Zenodo operations: checksum comparison, new record creation, version updates, and metadata management. Assumes PDFs are already generated.

python3 scripts/zenodo.py                     # dry run (show what would happen)
python3 scripts/zenodo.py --publish           # process and publish all changes
python3 scripts/zenodo.py --publish rtc mmn   # only specific essays
python3 scripts/zenodo.py --force rtc         # ignore checksum, force update
python3 scripts/zenodo.py --sync-index        # update index.md with concept DOIs from Zenodo

Requires: python3, requests (Python package)

Logic per essay:

  • Unchanged (checksum matches stored): skip
  • New (no stored checksum, no DOI in index.md): create new Zenodo record
  • Changed (checksum differs, has DOI): create new version of existing record

Extracts metadata from each essay .md file (title, subtitle, abstract, **Finalized:** Month Year → publication_date). Enriches Zenodo records with LOC subject identifiers, essay-specific keywords, related identifiers, and ORCID.

Saves checksums to exports/pdf-checksums after successful operations.

Legacy scripts (superseded): check-pdfs.sh, zenodo-upload.sh, zenodo-update-pdf.sh, zenodo-update-all.sh

serve.py

Starts or restarts the local Jekyll development server. Kills any existing Jekyll process before starting a fresh one.

python3 scripts/serve.py

Serves at http://127.0.0.1:4000/return-to-consciousness/. Press Ctrl+C to stop.

analyze.py

Sends essays to LLMs via the OpenRouter API for quality analysis. Outputs to _analysis/<essay>_<hash>_<model>.md. The 4-character hash in the filename is derived from the essay content, so re-running after edits produces new files rather than overwriting old ones (stale files are moved to _analysis/archive/).

python3 scripts/analyze.py                        # all essays and models from config
python3 scripts/analyze.py tcj                   # specific essay, all models
python3 scripts/analyze.py tcj --model openai/gpt-4o  # specific essay and model
python3 scripts/analyze.py --force tcj           # overwrite existing output files

Requires: python3, requests, pyyaml; OPENROUTER_API_KEY in environment or .env

Config is in scripts/analyze.yaml (essays list, models list, prompt). Token: OPENROUTER_API_KEY=your_key in .env.

analyze_report.py

Extracts numeric scores from _analysis/ files and produces a formatted report. Shows per-essay scores by model and a summary table with averages across the latest hash for each essay.

python3 scripts/analyze_report.py                 # write to exports/report.md
python3 scripts/analyze_report.py --stdout        # print to terminal
python3 scripts/analyze_report.py --output path/to/report.md

Default output: exports/report.md (Jekyll page, noindex: true).

update-headers.py

Syncs essay page counts and reading times across all three locations (essay file, index.md, readers-guide.md). Reads page counts from generated PDFs via pdfinfo; computes reading time from word count at 220 wpm. Default is a dry run.

python3 scripts/update-headers.py                 # dry run (show what would change)
python3 scripts/update-headers.py --update        # apply changes to all essays
python3 scripts/update-headers.py --update tcj amr  # apply to specific essays only

Requires: pdfinfo (from poppler; install via brew install poppler)

Run after ./scripts/generate-pdfs.sh to keep metadata in sync.

Zenodo Integration

  • Each essay has a concept DOI (permanent, always resolves to latest version) stored in index.md
  • Version DOIs change with each upload; concept DOIs do not
  • Token stored in .env file (not versioned): ZENODO_TOKEN=your_token
  • Load token before running scripts: source .env
  • Workflow for updating essays: regenerate PDFs, then python3 scripts/zenodo.py --publish
  • Workflow for a single essay: python3 scripts/zenodo.py --publish <abbrev>
  • After publishing new records, sync concept DOIs to index.md: python3 scripts/zenodo.py --sync-index

Essay Metadata Conventions

Each essay displays page count and reading time in three places that must stay in sync:

  1. Essay file (e.g., cac.md): *X pages · ~Y min read · [PDF](...)* near the top
  2. index.md: *X pages* · [PDF](...) in each essay listing
  3. readers-guide.md: *X pages* · [Read](...) · [PDF](...) in each essay entry

Page count

Use the PDF page count as the authoritative source. After regenerating PDFs (./scripts/generate-pdfs.sh), verify with:

pdfinfo exports/pdf/<essay>.pdf | grep Pages

Update all three locations when page counts change.

Reading time

Calculate from word count at ~220 words per minute, rounded to nearest minute:

wc -w <essay>.md

Divide by 220 and round. This rate reflects academic-density prose (not skimming).

When to update

Update page counts and reading times after any substantive content edit to an essay. Minor edits (typo fixes, link changes) typically don’t change these values.

Use update-headers.py to automate syncing across all three locations after regenerating PDFs.

Abstracts

Scholarly best practice is 150–250 words per abstract. The project’s abstracts currently range from ~115 to ~220 words. When writing or editing an abstract:

  • Stay within the 150–250 word range
  • Include: central claim, method/approach, key contributions, epistemic standard
  • Avoid: literature review, citations, background that belongs in the introduction
  • Compress by naming the structural claim once rather than enumerating frameworks it responds to
  • The abstract must stand alone — a reader should understand the essay’s scope without reading further

AI Assistant Preferences

  • Prefer Python for bulk file operations and multi-file text transformations (e.g., python3 -c "..."). Bash/sed is fine for single-file one-liners.

Build

Jekyll site served via GitHub Pages.

python3 scripts/serve.py    # local preview (kills existing Jekyll, starts fresh)
bundle exec jekyll serve    # alternative: manual local preview