docs: How It Works section#73
Draft
coderdan wants to merge 12 commits into
Draft
Conversation
Add the traditional-field-encryption page walking through why bytea column encryption breaks equality lookups, LIKE, and ORDER BY, plus a what-searchable-encryption-solves page framing the use cases.
Relocate traditional-field-encryption and what-searchable-encryption-solves from the un-navigated how-it-works/ dir into concepts/, and order the section problem -> motivation -> mechanism.
…ting Started Update the section title in meta.json and the landing page, and reorder the top-level nav so the section sits directly under Getting Started.
…works Rename content/docs/concepts -> content/docs/how-it-works so URLs match the section name. Update the top-level nav key, all internal /concepts links (leaving /reference/eql/core-concepts untouched), the three "Concepts" section labels, and the /concepts destinations in v2-redirects.mjs. Add /concepts -> /how-it-works redirects (307) so the previously-live preview URLs still resolve.
Rename traditional-field-encryption -> why-field-encryption-fails and what-searchable-encryption-solves -> making-encryption-searchable, and add sql-support, key-management, and cryptography stub pages. Reorder the nav to match. Work in progress — several pages are still TODO stubs.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…on redirect Fix the "seachable" title typo (and an "Its"/"It's" slip), write real descriptions for the sql-support, key-management, and cryptography stubs, and redirect the landing-page-less /how-it-works root to its first page, why-field-encryption-fails.
Port the RLS-and-TDE comparison and the branded Mermaid component from the concepts-comparisons branch into the new How It Works section, and add a new RBAC comparison page. - rls-and-tde: authorization at the database connection; retargets the searchable-encryption card to /how-it-works/making-encryption-searchable - rbac: application-level authorization (CASL, the CanCanCan successor); the fails-open vs fails-closed contrast with encryption - mermaid.tsx: CipherStash-branded light/dark themeVariables - compare/meta.json: list both pages in the section nav Claude-Session: https://claude.ai/code/session_01NkxKebM3qffTB7FayXsfxP
…-fails Replace the TODO placeholders with worked pgcrypto examples: - pgp_sym_encrypt INSERT and pgp_sym_decrypt SELECT, keeping the secret key inline to set up the key-in-the-query point - a search-by-email query that encrypts the term with the same key and still returns 0 rows - a same-value-twice pgp_sym_encrypt SELECT showing two different ciphertexts, demonstrating why equality, GROUP BY and JOIN break Claude-Session: https://claude.ai/code/session_01NkxKebM3qffTB7FayXsfxP
…ction Fill in the WHERE-on-pgp_sym_decrypt example (the earlier failed email lookup now succeeds), explain why it forces a full table scan, then show that a functional index does work but writes the decryption key verbatim into the index expression, visible via \d, pg_indexes, and pg_dump. Output verified against Postgres 17 + pgcrypto. Claude-Session: https://claude.ai/code/session_01NkxKebM3qffTB7FayXsfxP
- Prose body copy: warm near-white -> cool gray (hsl 240), 14px, tighter line-height. Headings, links, and bold keep the full foreground. - Shift all text tokens off the warm hue 42 to a cool 240 at low saturation. - Page description under the H1: size down to text-base and use the same muted-foreground the sidebar nav items use. Claude-Session: https://claude.ai/code/session_01NkxKebM3qffTB7FayXsfxP
…light
Enable transformerMetaHighlight so `{n}` line highlighting works in code
fences (Fumadocs bundles only the comment-marker notation transformers,
which don't work in plain ```text blocks). Pin @shikijs/transformers to
match fumadocs.
Use it to highlight the index line that exposes the pgcrypto key in \d
output, replacing the hand-aligned ASCII caret. Also picks up copy tweaks
on the page.
Claude-Session: https://claude.ai/code/session_01NkxKebM3qffTB7FayXsfxP
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new How It Works section to the docs and wires it into the nav (renamed from the old Concepts section, moved directly below Getting Started).
🚧 Draft — work in progress. Opening early to track the work; still being written.
What's here
/how-it-works(folder renamed fromconcepts/, with/concepts → /how-it-worksredirects and all internal links updated)./how-it-worksroot redirects to the first page (why-field-encryption-fails) since the section has no landing page.why-field-encryption-fails— walks through whybyteacolumn encryption breaks equality,LIKE, andORDER BY.making-encryption-searchable— the use cases value-level searchable encryption enables.sql-support,key-management,cryptography— stub pages (frontmatter only, body content to come).compare— existing comparisons page.Still to do
sql-support,key-management,cryptography(currently frontmatter-only stubs).searchable-encryption.mdx(still on disk, no longer in nav).seachablesearchable".descriptionfrontmatter on the stub pages./how-it-worksnow redirects to the first page.Notes
/concepts → /how-it-worksand/how-it-works → first pageredirects are temporary (307) since the v2 IA isn't canonical yet.