From 2be644de5011f8092e547152f577bf9da72f52bb Mon Sep 17 00:00:00 2001 From: Alister Lewis-Bowen Date: Mon, 13 Apr 2026 18:46:37 -0400 Subject: [PATCH] Mirror repo layout in cloud storage for symlink correctness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Breaking change** for existing instances — see migration note below. Previously, cloud storage used a flat layout with `library-` prefixed names: $LIBRARY_BASE/library-findings/ $LIBRARY_BASE/NAME/ (PDFs) $LIBRARY_BASE/library-indexed/NAME/ (indexed output) Now it mirrors the repo structure exactly: $LIBRARY_BASE/findings/ $LIBRARY_BASE/collections/NAME/pdfs/ $LIBRARY_BASE/collections/NAME/indexed/ This makes relative links in findings/*.md (e.g. ../collections/NAME/indexed/SLUG/pages/page-N.png) resolve correctly when apps (Typora, terminal Markdown viewers) resolve symlinks to their real filesystem path rather than following the symlink path. Files changed: - init-symlinks.sh: update build_links() and header comments - bootstrap.sh: update Phase 1 mkdir paths - README.md: update cloud layout diagram and LINKS override example - .env.template: update LIBRARY_BASE description Migration for existing instances: 1. In cloud storage, rename/move: library-findings/ → findings/ NAME/ → collections/NAME/pdfs/ library-indexed/NAME/ → collections/NAME/indexed/ 2. Remove existing repo symlinks 3. Run ./init-symlinks.sh Co-Authored-By: Claude Sonnet 4.6 --- .env.template | 4 ++-- README.md | 26 ++++++++++++++------------ bootstrap.sh | 12 ++++++------ init-symlinks.sh | 18 +++++++++--------- 4 files changed, 31 insertions(+), 29 deletions(-) diff --git a/.env.template b/.env.template index 7f9940b..5741603 100644 --- a/.env.template +++ b/.env.template @@ -8,8 +8,8 @@ # # Edit .env and set LIBRARY_BASE # LIBRARY_BASE — absolute path to the root of your cloud-synced library storage. -# This is the directory that contains your collection PDF directories and -# library-indexed/ output. Used by init-symlinks.sh to create local symlinks. +# This directory will be structured to mirror the repo layout (findings/ and +# collections/NAME/{pdfs,indexed}/). Used by init-symlinks.sh to create local symlinks. # # Examples: # LIBRARY_BASE="${HOME}/Dropbox/my-library" diff --git a/README.md b/README.md index 92c6061..c4b6675 100644 --- a/README.md +++ b/README.md @@ -180,20 +180,22 @@ to cloud folders work seamlessly with version control. ### Recommended cloud folder layout -A clean convention is to store each collection's PDFs in a named folder, and use `library-` prefixed -folders for the derived library assets (indexed output and findings). For example, using Dropbox: +The cloud storage layout mirrors the repo structure exactly. For example, using Dropbox: ```text ~/Dropbox/my-library/ -├── collection-a/ ← PDFs for collection A -├── collection-b/ ← PDFs for collection B -├── library-findings/ ← research findings (symlinked to findings/) -└── library-indexed/ ← converted indexed output - ├── collection-a/ (symlinked to collections/collection-a/indexed) - └── collection-b/ (symlinked to collections/collection-b/indexed) +├── findings/ ← research findings (symlinked to findings/) +└── collections/ + ├── collection-a/ + │ ├── pdfs/ ← PDFs for collection A (symlinked to collections/collection-a/pdfs) + │ └── indexed/ ← converted output (symlinked to collections/collection-a/indexed) + └── collection-b/ + ├── pdfs/ + └── indexed/ ``` -The `library-` prefix distinguishes library infrastructure from per-collection PDF archives at a glance. +Mirroring the repo layout means relative links in `findings/*.md` resolve correctly when +apps resolve symlinks to their real filesystem path. ### One-command reconstruction with bootstrap.sh @@ -220,9 +222,9 @@ array in `.env`: ```bash # .env LINKS=( - "findings:${LIBRARY_BASE}/library-findings" - "collections/collection-a/pdfs:${LIBRARY_BASE}/collection-a" - "collections/collection-a/indexed:${LIBRARY_BASE}/library-indexed/collection-a" + "findings:${LIBRARY_BASE}/findings" + "collections/collection-a/pdfs:${LIBRARY_BASE}/collections/collection-a/pdfs" + "collections/collection-a/indexed:${LIBRARY_BASE}/collections/collection-a/indexed" ) ``` diff --git a/bootstrap.sh b/bootstrap.sh index d17cd95..1af95cf 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -90,16 +90,16 @@ parse_source_url() { pfb heading "Creating cloud-storage directories" "☁️" echo -mkdir -p "${LIBRARY_BASE}/library-findings" -pfb success "READY ${LIBRARY_BASE}/library-findings" +mkdir -p "${LIBRARY_BASE}/findings" +pfb success "READY ${LIBRARY_BASE}/findings" for col_dir in "${SCRIPT_DIR}/collections"/*/; do [[ -d "${col_dir}" ]] || continue name="$(basename "${col_dir}")" - mkdir -p "${LIBRARY_BASE}/${name}" - pfb success "READY ${LIBRARY_BASE}/${name}" - mkdir -p "${LIBRARY_BASE}/library-indexed/${name}" - pfb success "READY ${LIBRARY_BASE}/library-indexed/${name}" + mkdir -p "${LIBRARY_BASE}/collections/${name}/pdfs" + pfb success "READY ${LIBRARY_BASE}/collections/${name}/pdfs" + mkdir -p "${LIBRARY_BASE}/collections/${name}/indexed" + pfb success "READY ${LIBRARY_BASE}/collections/${name}/indexed" done echo diff --git a/init-symlinks.sh b/init-symlinks.sh index aa22556..eb875b8 100755 --- a/init-symlinks.sh +++ b/init-symlinks.sh @@ -17,15 +17,15 @@ # See .env.template for examples. # # LINKS are auto-derived from collections/*/ using the naming convention: -# collections/NAME/pdfs → ${LIBRARY_BASE}/NAME -# collections/NAME/indexed → ${LIBRARY_BASE}/library-indexed/NAME -# findings → ${LIBRARY_BASE}/library-findings +# collections/NAME/pdfs → ${LIBRARY_BASE}/collections/NAME/pdfs +# collections/NAME/indexed → ${LIBRARY_BASE}/collections/NAME/indexed +# findings → ${LIBRARY_BASE}/findings # # To override, define a LINKS array in .env before running: # LINKS=( -# "findings:${LIBRARY_BASE}/library-findings" -# "collections/NAME/pdfs:${LIBRARY_BASE}/NAME" -# "collections/NAME/indexed:${LIBRARY_BASE}/library-indexed/NAME" +# "findings:${LIBRARY_BASE}/findings" +# "collections/NAME/pdfs:${LIBRARY_BASE}/collections/NAME/pdfs" +# "collections/NAME/indexed:${LIBRARY_BASE}/collections/NAME/indexed" # ) set -euo pipefail @@ -75,12 +75,12 @@ fi # @side_effects Populates the global LINKS array. build_links() { LINKS=() - LINKS+=("findings:${LIBRARY_BASE}/library-findings") + LINKS+=("findings:${LIBRARY_BASE}/findings") for col_dir in "${SCRIPT_DIR}/collections"/*/; do [[ -d "${col_dir}" ]] || continue name="$(basename "${col_dir}")" - LINKS+=("collections/${name}/pdfs:${LIBRARY_BASE}/${name}") - LINKS+=("collections/${name}/indexed:${LIBRARY_BASE}/library-indexed/${name}") + LINKS+=("collections/${name}/pdfs:${LIBRARY_BASE}/collections/${name}/pdfs") + LINKS+=("collections/${name}/indexed:${LIBRARY_BASE}/collections/${name}/indexed") done }