Skip to content

Mirror repo layout in cloud storage for symlink correctness#29

Merged
ali5ter merged 1 commit into
mainfrom
feature/mirror-repo-layout-in-cloud-storage
Apr 13, 2026
Merged

Mirror repo layout in cloud storage for symlink correctness#29
ali5ter merged 1 commit into
mainfrom
feature/mirror-repo-layout-in-cloud-storage

Conversation

@ali5ter
Copy link
Copy Markdown
Owner

@ali5ter ali5ter commented Apr 13, 2026

Summary

  • Changes cloud storage directory layout to mirror the repo structure exactly
  • Fixes relative links in findings/*.md not resolving in Typora and other apps that resolve symlinks to their real path
  • Updates init-symlinks.sh, bootstrap.sh, README.md, and .env.template

What changed

Before β€” flat layout with library- prefixed names:

$LIBRARY_BASE/
β”œβ”€β”€ library-findings/
β”œβ”€β”€ collection-a/              (PDFs)
β”œβ”€β”€ collection-b/
└── library-indexed/
    β”œβ”€β”€ collection-a/          (indexed output)
    └── collection-b/

After β€” mirrors repo layout:

$LIBRARY_BASE/
β”œβ”€β”€ findings/
└── collections/
    β”œβ”€β”€ collection-a/
    β”‚   β”œβ”€β”€ pdfs/
    β”‚   └── indexed/
    └── collection-b/
        β”œβ”€β”€ pdfs/
        └── indexed/

Why

Relative links in findings/*.md use paths like ../collections/NAME/indexed/SLUG/pages/page-N.png.
When apps resolve the findings/ symlink to its real path before computing relative links, ../collections/
resolves to a path that doesn't exist under the old flat layout. The new layout makes the real paths
siblings, so relative links work everywhere.

Breaking change β€” migration for existing instances

# In cloud storage, rename/move:
mv $LIBRARY_BASE/library-findings        $LIBRARY_BASE/findings
mv $LIBRARY_BASE/NAME                    $LIBRARY_BASE/collections/NAME/pdfs    # per collection
mv $LIBRARY_BASE/library-indexed/NAME    $LIBRARY_BASE/collections/NAME/indexed # per collection

# Remove existing repo symlinks
rm findings
for d in collections/*/; do rm -f "${d}pdfs" "${d}indexed"; done

# Recreate
./init-symlinks.sh

Moves within the same cloud storage account are instant (server-side rename) β€” no re-upload needed.

**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 <noreply@anthropic.com>
@ali5ter ali5ter merged commit e9925ab into main Apr 13, 2026
1 check passed
@ali5ter ali5ter deleted the feature/mirror-repo-layout-in-cloud-storage branch April 13, 2026 22:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant