User Guide

• What it is
• The home page
• Reading
• Card buttons
• Your own files
• Follow other blogs
• On a phone
• Public directory
• Follow this site
• FAQ

0What it is

ZhiTree Books is a personal digital library: the site owner puts notes, books, PDFs and small web tools into a folder, and they become cards on a web page. No sign-up, no login: open it and read. You can do three things:

1The home page

1. My shelf / Public directory: two spaces, one click to switch. “My shelf” is the site’s own books plus the files you add; the “Public directory” is covered in section 6.
2. Categories and tags: click a category to see only that kind, click a tag to filter by topic. The “Card index” below lists the titles in each category; click one to jump to its card.
3. Search: titles, summaries and keywords together. Press / to jump straight to the search box. Turn on “Full text” beside it to search the words inside books too; results show a snippet and “Page N”, and a click opens the document at that place (only in “My shelf”, done in your browser, nothing is uploaded). The public directory searches only what a book’s information page says: title, author, language, pages, contents, summary and keywords.
4. Cards: cover, title, summary, reading time. Click one to start reading. The small tag at the top right is the file type (MD / PDF / TXT / APP…); “APP” is a small web tool.
5. Add: bring in your own files, see section 4.

To the right of the search box you also find: All / 中 / EN (show one language of content only), sort (recently added / publication date / recently read / title; the public directory is newest first), the list / card view and Subscribe. At the bottom left you can switch the interface language (“Auto” follows the system; the button beside it switches to the other language) and the theme (system / light / dark).

2Reading

Click any card to open the reader. Every format shares the same row of buttons:

1. Back: return to the shelf (or press Esc).
2. Previous / Next: page through the current list in order (or press ← →).
3. Contents: takes the headings from the text; click one to jump there, and it marks where you are. The “Bookmarks” tab sits beside it.
4. Reading settings (Aa): change the colour and the text size, see the next picture.
5. Save: download this piece as a web page (HTML), or print / save it as PDF. A page shown as it is can only be printed; a PDF is saved with the browser’s own tools and this button is grey.
6. Bookmark: remembers the place you are at now; click it in “Bookmarks” later to come back.
7. Featured / Open in new tab: mark the whole piece as a favourite, or open just this page in a tab of its own.

While you scroll, your progress is saved automatically and you come back to the same place next time; “Continue reading” at the top of the home page lists the pieces you left half-read. On a phone, once the Contents, Reading settings or Save panel is open, a tap on the empty part of the page closes it (the Contents panel can also be swiped back to the right); the same goes for the left list.

3Card buttons

4Your own files

1. Click Add at the top right (or just drag files onto the page).
2. Click the dashed box to choose files; you can choose many at once. HTML, Markdown, TXT and PDF are supported, up to 30 MB each.
3. Each file can get its own title and summary; pick a collection and a category.
4. Click Save. The page switches to that collection by itself.

Back up and restore: moving devices, not losing things

Your files, collections, subscriptions, reading places and bookmarks live only in this browser, so make a backup before you switch device or clear the site’s data. Click Back up & restore at the bottom left:

• Export a full backup: one .zip with every file you added and all your settings.
• Export the list and settings only: a tiny .json without file contents, a way to take your saved links, subscriptions, collections and reading places to another device first.
• Restore: choose a backup file; the page first tells you what is in it and what is already here, and only “Merge into my shelf” imports it. It only merges; nothing you have now is deleted, and files with the same content are not added twice.

The backup file is made by your browser and saved on your own device; it never passes through a server. The site’s own books and the files of a folder you connected are not in it. The “What is this?” note shown on the first visit can be brought back with “What is this?” at the bottom left.

Sync (optional): one shelf on several devices

When the site has a sync service, there is a Sync button at the bottom left (if not, the site has none). It is optional: everything works without it; no sign-up, no password.

1. On the first device click Sync → Turn sync on and make a sync code and save the code at once (a password manager is a good place).
2. On another device click Sync, type the code under “Already turned sync on on another device?” and click Connect.
3. After that, changes sync by themselves a few seconds later, and once more when you come back to the page; “Sync now” works any time.

• What syncs: your list, saved links, subscriptions, collections, reading places, bookmarks, stars and pins; small text files (Markdown, TXT, HTML, up to about 1 MB each) with their content, fetched on another device when opened (the latest few ahead of time).
• What does not: large files such as PDFs sync only as a list entry (the card says “List only”) and their content does not go over; to take them to another device use “Back up & restore” on the original. The articles of a subscription do not sync: each device reads them from the feed.
• How private: the encryption happens in your browser; the sync service sees only scrambled data and can read no title and no text; the code is kept only as a hash. The sync code is the key: lose it and nothing can bring it back; whoever has it can read your shelf.
• Limits: the free space is about 9 MB; when it is full, new files sync only as a list entry; after half a year (180 days) without use the space is cleared. When two devices changed the same thing at once, the later reading place wins, bookmarks are combined, and otherwise the device you are using now wins; a change beats a deletion on the other side.
• Turning it off: “Turn sync off on this device” deletes nothing here; “Delete the cloud data” empties the sync space and leaves what is on every device alone.

After a good while of use the page asks you once: if “large-file sync” (PDFs and more, with more room) were added later, would you pay for it? Your answer goes to the sync service only as an anonymous count, with nothing that could identify you.

Write a note: like Apple Notes on a phone

On a computer click the pen in the top bar, on a phone the round pen button at the bottom right (“Write a note” in the Add window does the same): a full-page editor opens.

• On a phone: what you see is what you get. Typing is done by the phone’s own keyboard, word picker, dictation and magnifier, and the first line is the title. One row of buttons sits above the keyboard: Aa (heading, subheading, body, bold, italic, strikethrough, quote, numbered), to-do (a circle, tap to tick), list, link, picture, undo, redo; tapping them does not hide the keyboard. Type - , 1. , #, [] or > at the start of a line and a space, and it becomes a list, numbered list, heading, to-do or quote; in a list Enter starts the next item, and Enter on an empty item ends the list.
• Words, links and pictures: pasting brings only the words (no colours or fonts from elsewhere); pasting an address makes a link, pasting a picture’s address makes the picture; or tap “link” / “picture” and type the address (https:// is added if missing). A picture is only a link, no picture file is kept, so it takes no room in the browser and does not touch backup or sync; pasting a picture file asks you to paste its link instead.
• On a computer it starts as Markdown: write on the left, a live preview on the right, the toolbar on top; switch between the two with Aa (the last button of the Markdown toolbar) or MD inside Aa; the choice is remembered in this browser. A note that uses something document editing cannot show (a table, web code) is opened as Markdown automatically, so nothing is lost.
• It saves as you type: a moment after you stop, in this browser; no Save button. Words written as #tag become the note’s keywords; closing with nothing written leaves no empty note behind.
• Edit again: the pen on the card (behind the “…” on a phone) or in the reader’s top bar. Back, Esc and “Done” all save first. A note appears on the shelf like any file: search it, back it up, sync it.

Collections: a batch of files kept together

The files of one import can go into one collection. Once a collection is selected, the cards, categories, tags, search and “Continue reading” show only that collection, which keeps the shelf tidy.

• Switch: on a computer use the “Collection” drop-down above the cards; on a phone tap the index button at the top left, and the collections are at the top of the left list.
• Manage: create, rename, delete. Deleting a collection deletes the files in it; it asks first.
• Change collection: “Move to another category” on a card can put a file into a different collection.

Following: subscribe to other people’s blogs and feeds

Not sure what to follow? “Recommended” in the left list (or #recommend after the address) holds about a hundred blogs and columns picked by the site owner, sorted into tech, business, books, supply chain, science and more, the busiest first in each. The first group, “Hot lists & trends”, holds platform charts and busy communities: GitHub Trending, Juejin, V2EX, Bilibili popular, NetEase rising songs, Zhihu and Weibo, plus Hacker News, Product Hunt, Reddit, Lobsters and headlines of finance, academia and music. After you subscribe to a hot list, each update is what is on the platform’s chart right now, each entry with its rank and heat, shown in the page where possible (see below); only the lists the site’s service actually offers are shown. For all the lists (Douyin, Xiaohongshu, WeChat articles, Xueqiu, Google Trends, arXiv, WeRead’s novel chart and more) click “Hot lists” on the left of the public space: pick a column (Top stories, Tech & dev, Finance, World, AI & research, Books & media) and then a platform beside it; what is behind a row is shown in the page where it can be: videos and songs of Bilibili, YouTube and NetEase play in a window with the platform’s own player; news, blogs, V2EX topics, Zhihu Daily and the README of a GitHub repository are read in the reader; an Apple Podcasts show opens as its latest episodes, one click plays it in the bar at the foot; a hot search that is only a phrase (Weibo, Douyin, Zhihu) becomes a card (its heat, what the platform says about it, plus the news about it, each readable in the reader). Only what the platforms do not allow (Zhihu answers, WeChat articles, QQ Music) goes to the original site; its link is at the foot of the card. Every list can be subscribed to (“Subscribe to this list”), and the hot-list platforms (Zhihu, Weibo, Bilibili, GitHub …) are fixed in the “Platforms” tab of the public directory: open one for the cards of today’s list, with “Live hot list” beside it. Tick “Subscribe” and click “Subscribe” to follow several at once; tick “Push for review” and click “Push for review” to send them to the public directory, where the owner reviews them. What you follow already, or what the directory lists already, shows as done. The language filter and the search box work on them too.

For a blog you like to read, you need not visit its site to see whether there is something new: in the “Add” window switch to Subscribe and subscribe to it into your own shelf.

1. Click Add and switch to the Subscribe tab. “Try these” under it lists a few sources the site owner picked: one click subscribes, you can subscribe to several in a row and click “Done” to go back to the shelf.
2. Paste an address: a blog’s home page or a feed (RSS / Atom / JSON Feed) both work; click Look up. The page tells you what it is called and which articles came last.
3. Give the subscription a collection name and click Subscribe.

• Articles are read here, not on another site: when a feed carries the full text, the text of the latest articles is kept (the card says “Full text”). When a feed carries only excerpts, the “update service” reads the original page when you open it, extracts the article and shows it in the reader (some pages take ten seconds or more); the text is kept in your browser, so next time it opens at once, and the newest few are read ahead while the page is idle. “Read the original” is in the top bar and at the end. Like a link you saved, it can be searched, starred, pinned and hidden. In the reading settings you can also download the article as a web page (HTML) or print / save it as PDF.
• Pages that cannot be read: pages behind a login or a paywall, with a bot check, drawn by scripts only, PDFs, and pages whose robots.txt keeps programs out cannot be read here. The reader says why and offers an “Open the original” button; the card is marked “Original only”, and later a click opens the original in a new tab at once (it is tried again after a week).
• When it updates: when you open the page (if the last update is over 3 hours old), and any time you click “Refresh”. A web page cannot update in the background, so nothing is pushed to you; with no network you see what was stored last time. Each subscription keeps its latest 60 articles (those you starred or pinned are never cleared).
• What to listen to today: in the sidebar, where “Audio” was. The title is followed by a small line (“New songs and shows every day, never the same twice”); below it, on the left a Music | Podcasts switch, on the right the sort and the cards / rows button; then one strip of choices: the charts and play lists of the day first (the daily picks; Chinese, Western, Korean and Japanese hits; Deezer’s Top 100 lists …; for podcasts the charts of several countries and “Shows of the directory”), then the styles (rock, hip-hop, electronic, jazz, classical, chill …) or the podcast categories (news, business, stories, learn English …). On a phone the strip scrolls sideways and a swipe left or right on the songs moves to the next or previous list. Straight under the strip are the songs or shows, as rows by default; every list holds 200, thirty are shown and the next thirty are added by themselves when you get near the end. A row says only the title, who it is by (artist or show), how hot it is (its place in a chart) and “Preview” (only for a preview piece); “Play all” starts from the first. Whole songs and whole episodes, and previews (the 30 seconds Deezer and Apple Music publish; the ↗ goes to the full song there) go into the player bar at the foot of the page, and the ones after it in the list play on (one that cannot be played is skipped), with the licence in the “Now playing” page; YouTube’s music videos open in YouTube’s own player in a window and usually cannot be opened in mainland China (marked “Global”). What comes first follows the interface language: on an English phone it is Western songs and the US and UK podcast charts; tap the language button at the bottom left to change it. The discovery page keeps a small “What to listen to today” block; “Open” takes you to the whole page. Everybody sees the same lists on the same day, and what you listen to is not recorded.
• Focus mode (for studying or meditating): press “Focus” above the song list, ◎ in the player bar, or “Focus mode” in the “Now playing” page, and the whole screen holds only a slowly changing pattern (Breath / Aurora / Dark; tap to change) and the title in small dim letters, while a whole song or a whole episode starts by itself (30-second previews do not count). The buttons disappear after four seconds and come back when you move the mouse or touch the screen: previous / pause / next, music ↔ podcasts, a timer (15 / 25 / 45 / 60 minutes, it pauses when the time is up) and the pattern. Esc or × leaves it and the sound goes on. While reading, “Focus reading” in the reader’s bar (on a phone it is in the “Aa” settings) hides every button and leaves the text and a small pill at the bottom right (pause, next, the pattern page, leave); the sound starts by itself, unless you paused it in the pill last time.
• Podcasts: listen and read: follow a podcast (paste its RSS address, as for a blog) and every episode’s card has a “Podcast” mark and a play button on its cover. Press it, or just click the card’s title or cover, and it plays; a player bar appears at the foot of the page: previous / back 15 seconds / play / forward 30 seconds / next, a progress bar with the time, speed and volume; a click on its cover opens the “Now playing” page: the show notes, speed (0.75× to 2×), a sleep timer (15 / 30 / 60 minutes, or the end of this episode) and the play list; when one ends the next starts. Podcasts on the “Recommended” page have a “Listen” button: the newest episode, without subscribing. You can read articles and move around the shelf while it plays and the sound does not stop (keep this page open); on a phone the lock screen and the notification shade have the controls too (where the browser supports it). How far you listened is remembered and “play” carries on from there; all of it stays in your browser. The sound comes straight from the show’s own server to your browser, this site does not touch or keep it; a few shows do not let other sites play them, then you get “Open the original”.
• If you paste a single article (not a blog): it has no feed to follow, so it is saved as one link and is not updated; when it can be read, its text is kept too and read in the reader.
• Manage: in the collection’s “Manage” you can refresh, “Mark all read” and unsubscribe (the stored articles are removed with it). An article you delete does not come back at the next update.
• Another device: in “Manage” (or “Import / export your subscriptions” in the Add window) export an OPML file or copy a link to the list, and import it or open the link on the other device. Only the list of subscriptions (a series of addresses) is synced; articles and read marks are kept by each device itself. The OPML file also works with readers such as Feedly.
• Privacy: other people’s sites do not let a web page read them directly, so the site’s “update service” reads them for you: the address you subscribe to is sent to it, it reads the titles and summaries and hands them to your browser, and it stores nothing itself. The list of subscriptions lives only in your browser.

5On a phone

Install it to the home screen and use it like an app

• Android (Chrome): open the site and tap “Install the app” at the bottom of the left column, or “Install app / Add to Home screen” in the browser menu.
• iPhone (Safari): tap the “Share” button at the bottom → “Add to Home Screen”.

Once installed it opens full screen, and the pages and files you have opened (up to 120) are kept, so you can read them again without a network.

Cards and gestures on a phone

• The card view is two columns: a card keeps its cover, title and one line of facts; the buttons besides the star (pin, hide, move, publish, new cover, delete …) are behind the “…” on the card: tap to open, tap elsewhere to close. The list button at the top right switches to one row per item.
• Swipe left or right while reading: left is the next article, right the previous one (in the order of the shelf’s current sort); at the ends it tells you. The top bar has no “Previous / Next” buttons any more; the contents panel keeps a pair for what cannot be swiped, such as a PDF. A code block or table that scrolls sideways does not turn the page by mistake; nor does a swipe with text selected, while zoomed in, or from the very edge of the screen (that is the system’s back gesture).
• Swipe on the shelf: right opens the left list, left closes it (on one row of the list, a swipe to the left shows that row’s buttons instead, see below).

The left index: collections, categories, swipe left to delete

Tap ≡ at the top left (or swipe right on the shelf) to open the left list: collections are at the top, then categories and tags, and the “Card index” at the bottom. Swipe one row of the index to the left and buttons appear underneath:

• Red “Delete”: for your own files; it asks first.
• Grey “Hide”: for the site’s books (which you cannot delete); it hides them in your browser only. Inside “Hidden” the button reads “Restore”.
• Swiping vertically still scrolls the list; once a row is open, tap elsewhere to close it again.

“Share to ZhiTree Books” from other apps (Android)

After installing it to the home screen, tap “Share” in a file manager, a chat app or the browser and pick “ZhiTree Books”: a shared PDF / Markdown / TXT / HTML opens the “Add” window, where you choose a collection and save; a shared web address is saved straight away as a “Saved link”. Right after the first install it takes the browser a while to refresh the app’s details (usually within a day; adding the icon again makes it immediate) before it shows in the share list. Safari on iPhone has no such feature: use “Add” and choose several files instead.

6Public directory and submitting

Click “Public directory” on the left to see one list made of many people’s blogs, articles, GitHub repositories and videos. It does not keep anyone’s full text: only the title, summary, the address of a cover image and a link back to the original. Click an article and it is read right in the reader (as in a subscription, the “update service” reads the original; pages that cannot be read, videos and repositories go to the original site); when you save it, the text you read is saved with it.

• Two levels: the public directory opens on a discovery page: no toolbar, no tag or shelf lists, only what is worth reading today, a row of column entries and one button, “All sources · platforms · tags ›”. Tap a column, search, or tap that button and you are in the whole directory; in the sidebar “Discover” sits beside “All / Articles / Audio …”: “Discover” takes you back, “All” or a type shows that kind in the whole directory.
• The top of the whole directory: under the title are two rows of tabs, “Columns / Platforms” (too many and they wrap onto more lines, no sideways swiping; on a phone only two lines show, the rest is behind “More”). The Columns side has eight columns: Unwind, AI & Tech, Learn & Research, Finance & Business (supply chain is inside), Work & Product, Video & Creators, Books & Depth, World Now (only those with content show). Every piece belongs to exactly one column, and inside a column a second line shows its domains (AI & Tech has Tech / Programming), so each column shows different articles; the Platforms side lists every platform that has programs: Zhihu, Weibo, WeChat accounts, Bilibili, YouTube, GitHub… (names are cut to 7 characters; first the fixed platforms, recognised by address, then the dynamic ones: every independent site counts as a platform of its own, the five busiest now show first and the rest sit behind “More N ▾”; links readers pasted go under “Other”). Both sides have a dropdown button: on the Platforms side it is “Programs” and lists every subscription program of the platform you are on, with a search box and tick boxes, and from then on the platform tabs show only those programs; on the Columns side it is “Columns” and lists the columns that have articles (each with its count), also with search and tick boxes, and from then on the Columns side shows only the articles of the ticked columns. What you tick is kept in your browser; tap “N ticked ✕” under the title to clear it.
• On a first visit it asks “What do you feel like reading?”: four moods (Unwind, Level up, Make sense of the news, Long reads); tap one and it ticks the matching columns for you; or tick a few columns yourself and tap “Show these columns”; “Just browse” and it never asks again. Only what you tap is remembered, the page never guesses, and you can change it any time in the “Columns” dropdown. Once you have ticked columns, the home page is your own: one small section for each ticked column (3 cards and “More ›”). Back after more than 30 days, a “You may have missed” section follows today’s; once you have read something there is also “Read lately”. Inside a column, domain or platform a line under the title says where you are (Column: AI & Tech ✕ …), and “Discover” in the sidebar clears every filter at once.
• The home page reads like “what to read today”: 3 to read today (one big picture card and two small ones, a new set every day, what you have read is not shown again) → Editor’s picks (called “For you” once you have read things; picture cards, Xiaohongshu style, in a tidy grid: three columns at most, two on a phone, every cover the same shape, every row the same height; a few from every topic or platform, mixed; once this browser has seen enough of what you opened, saved, followed and liked, the same cards are ordered by your interests, the data never leaves your device, one tap clears it; “Shuffle” takes the next ones) → Worth following (the owner’s picks and the busiest programs; what you follow is left out) → Latest (the same grid; what appeared above is not repeated). The “cards / list” button at the top right works everywhere (on a phone too): tap it and all the cards become one row each (a small cover, the title, two lines of summary, the numbers), tap again to go back. On a first visit, a line at the very top says “Open the guide”; tap it to read the guide, tap × and it does not come back. On a phone the first screen is one big card and two more, then a two-column grid.
• A card: the cover, the title, the summary, tags, the source and the date, and a bottom row with ♥ likes (tap to like, tap again to take it back), 👁 reads, 🔥 heat and the bookmark. At most one small “why look at this” label (#N on the chart, hot this week, because you read this program, N likes, N reads, owner’s pick, you follow it; none when there is nothing true to say); articles are no longer labelled “Article”, the language is shown only when it differs from the page’s (EN / 中文), the date reads “Today / Yesterday / 10-22”. An article with no picture gets a cover that carries the start of its summary (a text poster on the colour of its program); a hot list’s rank is the big number on its cover. Reading an article of the directory, two more buttons (like / dislike) sit at the bottom of the page.
• Sorting: newest, heat, recently read (remembered in your browser only), title. Cards show heat (the little flame).
• Where heat comes from: anonymous counters. An entry that is opened, liked, saved or subscribed to is counted once (one count per reader, per entry, per day); nobody is identified and no cookie is used; nothing is sent when the browser says “Do Not Track”.
• Save: the bookmark button on a card saves the link to your own shelf (kept in your browser only), marked “Saved link”.
• Subscribe: “Subscribe” inside the public directory follows the whole directory, one type, one tag or one shelf.
• Recommend a blog: paste its address (the blog’s home page or its RSS) in “Submit”. A feed can be submitted too; once the site owner approves it, its new articles enter the directory every day.

Sending your own content in: three ways, none needs an account

1. Paste an address: a blog, an article, a video, a GitHub repository or a PDF will do. Click “Check” first: the page tells you what it is, how many pieces it found and what the latest ones are, and it stops duplicates that “the directory already has”. When it looks right, tick “I have the right to publish this content” and click “Submit”. Just want to read it yourself, not make it public? The same address can be subscribed to straight into your shelf, with no review: click “Subscribe to this address instead” in the window (when the check finds a feed, the result has “Subscribe on my shelf” too), and you land in “Add → Subscribe” with the address filled in.
2. Write a post: switch to “Write a post” in the window, write or paste a Markdown article, and it carries the author name you give. Once approved the directory hosts it as a page (public, pictures not shown), and you can ask for it to be taken down at any time.
3. Click the globe icon on a card: every card in “My shelf” has one. If it has an address, that address is sent; for a Markdown / TXT file in your computer or browser, the text is sent; for things with no address, such as books, PDFs and web tools, only a book card (title, author, summary, tags; you can pick “a book / a list of books / a book to read online / a novel”) is made public, never the file.

After you submit, it goes to the owner’s review queue and the card shows “Sent, waiting for review”; once approved it appears in the public directory. Different spellings of an address (http / https, www, a trailing slash, tracking parameters) count as the same one; things whose title, author and summary are nearly the same are also stopped, and you are told which one they look like.

7Following this site (RSS)

This section is the other way round: following this website in your own RSS reader. (To follow other people’s writing, see section 4.) Click the green “Subscribe” button in the top bar: it has one-click “Subscribe in Feedly / Inoreader” links and a copy button. You can follow just a part: everything, one category or one tag, with the one you are looking at preselected. Once you follow it, your RSS reader (Feedly, Inoreader and so on) lets you know when there is something new.

8FAQ

Want to set up a site like this yourself? Switch to “Install & deploy”.

• What you need
• Run it locally
• Add content
• Pin this guide
• Deploy to Vercel
• Be found by search engines
• Public directory
• Review page
• Troubleshooting

0What you need

The project is one folder: index.html (the web page), serve.py (the local server), build_index.py and seo.py (run at deploy time), vercel.json (deploy settings), and library/ where your content lives.

1Run it on your own computer

Open a terminal in the project folder and run:

python serve.py

On Mac / Linux use python3 serve.py. The browser opens http://127.0.0.1:8000 by itself; use --port 9000 for another port. That is the one command; nothing else to install.

• Put files into library/ and they appear when you refresh the page; you can also click “Add” or drag files onto the page, which writes straight into library/.
• The page is now in “owner mode”: moving, deleting, pinning, starring and hiding on a card really change the files (stars, pins, hides and renamed titles are saved in library/_meta.json).
• The server accepts requests from this machine only; it can write files, so do not expose it to the internet. Restart it after you change serve.py.

2Adding content to the shelf

library/
├── books/      books
├── tools/      tools (small web apps)
├── notes/      personal notes
├── featured/   featured
└── _meta.json  stars, pins, hides, title edits (generated)

• A first-level folder is a category; a new folder becomes a new category by itself.
• A tool = a folder: a web tool made of index.html + css + js + images goes into library/tools/tool-name/, and the whole folder is one card; inside it use relative paths (style.css), not paths starting with /. This guide itself is kept that way: library/notes/guide/.
• HTML, Markdown, TXT and PDF are supported, up to 80 MB per file. For Word (.docx), save as PDF or Markdown first.

A Markdown file can start with front matter that sets the title, summary and keywords; in HTML use meta tags:

---
title: My title
description: A one-sentence summary
tags: [supply chain, reading]
featured: true     # mark as featured
pinned: true       # pin to top, seen by every visitor
---

<meta name="description" content="A one-sentence summary">
<meta name="keywords" content="supply chain, procurement">
<meta name="archive:pinned" content="true">

A second language for the same item

If a page exists in two languages, give each its own file and tell the site about the English one. A visitor who switches the interface to English then sees the English title and summary and opens the English page; a search engine gets both addresses and is told they are translations of each other.

---
title: 我的标题
title_en: My title
description_en: A one-sentence summary in English
tags_en: [supply chain, reading]
alt_en: en/index.html     # the English page, relative to this one, inside library/
---

<meta name="archive:title_en" content="My title">
<meta name="archive:description_en" content="A one-sentence summary in English">
<meta name="archive:keywords_en" content="supply chain, reading">
<meta name="archive:alt_en" content="en/index.html">

This guide is built this way: library/notes/guide/index.html is the Chinese page and library/notes/guide/en/index.html the English one.

3Putting this guide first

To make every visitor see this guide first, you pin it on your own computer and deploy again. Two ways, pick one:

1. Write it into the document (the easiest): add pinned: true to a Markdown file’s front matter, or <meta name="archive:pinned" content="true"> to an HTML file. A number such as pinned: 2 also works; the bigger the number, the nearer the front. This guide uses this way.
2. Click the pin on the page: open the page with python serve.py and click the pin on a card (it is written to library/_meta.json).

Then deploy again (next section). With several pinned, the last one pinned comes first.

4Deploy to Vercel

Vercel is a static / serverless platform and cannot run serve.py. When you deploy, it first runs the build scripts named in vercel.json, builds the site into dist/, and what goes online is dist/, not your original folder.

1. Install Node.js, then install the Vercel command line and log in:

   npm i -g vercel
   vercel login

2. Run vercel in the project folder and follow the prompts to create the project (answer a few questions the first time; pressing Enter all the way is fine).
3. Open vercel.json and change the address --site-url https://books.zhitree.cn in the build command to your own (the sitemap and the feeds use it).
4. Publish for real:

   vercel --prod

5. For your own domain: add it under Settings → Domains in the Vercel project and set up the DNS as it tells you.

• Every update after that: put things into library/ → take a look locally with serve.py → vercel --prod. New files appear only after you deploy again.
• Hidden items do not go online: dist/ has no hidden files and the list does not mention them; unhide one to publish it.
• The live shelf is read-only for every visitor: a visitor cannot add, move or delete anything on the server.
• If new content does not show, open https://your-domain/manifest.json and look at generated and items: if it is not in the list, what you deployed is not the latest files.
• For a local preview use serve.py, not vercel dev (it remembers the files that existed when it started, and files added or moved later give a 404).

Your name, contact, privacy and terms

about.html, privacy.html and terms.html are ordinary HTML; edit the text directly. Your name and contact go in site.json (it is not published):

{ "owner": "Your name or nickname", "contact": "you@example.com", "license": "CC BY-NC 4.0" }

5Be found by search engines

These are done for you at deploy time, and your original files are not changed by a single byte: missing tags are added to every page, pages with the full text are generated for Markdown / TXT, sitemap.xml and robots.txt are made, long Chinese file names become short, stable addresses, and the feeds are generated. Pages that have an English version get hreflang links in both directions and appear in the sitemap together, so that search engines show each reader the right language. You only need two steps:

1. Google Search Console: add your address and verify it, then submit sitemap.xml under “Sitemaps”. “Couldn’t fetch” right after you submit is common; it turns to “Success” a few hours to two days later.
2. Bing Webmaster Tools: you can simply “Import from Google Search Console”, or submit the same sitemap.xml.

To tell Bing and others about new addresses yourself (IndexNow):

python indexnow.py --init          # the first time only: makes a key and writes it to site.json
vercel --prod
python indexnow.py                 # after every deploy: sends only new and changed addresses

6Setting up the public directory and submissions (optional)

The data and the program of the public directory live in another project, shelf-directory (a folder next to this project); GitHub updates it every day and this site only displays it. Three steps:

1. Put it on GitHub: create a public repository and push shelf-directory to it; under Settings → Actions → General → Workflow permissions choose “Read and write”; then go to Actions → Daily → Run workflow once by hand.
2. Make this site show it: add "directory": "the address of the directory" (ending in /) to site.json and deploy again. “My shelf | Public directory” then appears on the left of the page.
3. Let visitors submit without a GitHub account: also deploy shelf-directory as a Vercel project (its api/submit.py is the submission service) and set these environment variables:

   Name	Value
   SHELF_REPO	user/repository
   SUBMIT_GITHUB_TOKEN	A token with read and write on this repository’s Issues only (plus read-only Contents)
   ALLOWED_ORIGINS	The web origins allowed to submit; by default your main site’s address
   IP_SALT	A long random string, used to make a short irreversible hash of each visitor’s address so each person’s submissions per day can be limited

   Write the address of the submission service (https://…/api/submit) into "submit_api" in shelf-directory/registry/config.json and push. After you change an environment variable, deploy once more for it to take effect.
4. Subscriptions switch on by themselves: api/feed.py in the same directory project is the “update service” used when a reader follows other people’s blogs (a web page cannot read other sites itself, so this reads for it, returns only titles, summaries and links, stores nothing, and needs no environment variables). The page finds it by replacing the /submit at the end of the submission service’s address with /feed, so as long as submit_api is right and your main site’s address is in ALLOWED_ORIGINS, the “Add” window shows the “Subscribe” tab. Each visitor has a soft limit on lookups per 10 minutes to prevent abuse.
5. Sync (optional, needs a Redis): api/sync.py in the same directory project is the “sync code” service; a reader’s list and small texts are kept in a Redis, encrypted (the server cannot read them). In the Vercel project’s Storage / Marketplace add an Upstash Redis and connect it to this project; it writes the environment variables by itself (KV_REST_API_URL + KV_REST_API_TOKEN, or UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN: both are accepted), then deploy once more. Open https://your-directory-site/api/sync: "configured": true means it is on and the page shows a “Sync” button. Optional variables: SYNC_QUOTA (characters per sync code, default 12 million), SYNC_TTL_DAYS (days of no use before it is cleared, default 180), SYNC_MAX_KEYS (no new sync code once the database holds more keys than this, default 6000, about 1000 codes). Each visitor can make at most 3 sync spaces a day. GET /api/sync also shows the anonymous counts of the “would you pay” question.

7The review page: manage with a password

Every request (the GitHub form, addresses submitted on the page, articles from a shelf) goes to one review page: https://your-directory-site/admin/.

Add two more in the directory project’s Vercel environment variables, and deploy again:

• Approving or rejecting changes only the data in the repository, no site needs to be deployed again. Entries already listed and hosted articles can also be taken down here.
• After login the browser holds a pass that expires (8 hours by default, 14 days if you tick “remember”), not a token. Changing the password or the token signs out every device that is logged in, at once.
• Without a password configured, the page falls back to “Log in with a GitHub token” and tells you what is missing on the server.

8Troubleshooting

Just want to use it? Back to “Using it”.