{"id":52092579,"url":"https://github.com/prof18/html-shelf","last_synced_at":"2026-08-04T07:30:39.288Z","repository":{"id":373777637,"uuid":"1316570506","full_name":"prof18/html-shelf","owner":"prof18","description":"Browse and read the HTML files in your Obsidian vault on mobile and desktop, without the file explorer.","archived":false,"fork":false,"pushed_at":"2026-07-29T21:57:31.000Z","size":607,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-29T23:10:30.647Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prof18.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2026-07-29T21:11:22.000Z","updated_at":"2026-07-29T21:57:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/prof18/html-shelf","commit_stats":null,"previous_names":["prof18/html-shelf"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/prof18/html-shelf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2Fhtml-shelf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2Fhtml-shelf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2Fhtml-shelf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2Fhtml-shelf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prof18","download_url":"https://codeload.github.com/prof18/html-shelf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof18%2Fhtml-shelf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36268177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-04T02:00:06.901Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-08-04T07:30:38.398Z","updated_at":"2026-08-04T07:30:39.280Z","avatar_url":"https://github.com/prof18.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HTML Shelf\n\nHTML Shelf discovers and reads the HTML files in your vault on mobile and desktop. It solves the awkward mobile workflow where HTML files are absent from Obsidian's file explorer or open in an external browser instead of alongside your notes.\n\n## Screenshots\n\n### Shelf on desktop\n\n![HTML Shelf listing synthetic fixture pages on desktop](docs/images/shelf-desktop.png)\n\n### Shelf on mobile\n\n\u003cp\u003e\n  \u003cimg src=\"docs/images/shelf-android.png\" alt=\"HTML Shelf homepage listing synthetic fixture pages on mobile\" width=\"280\"\u003e\n  \u003cimg src=\"docs/images/page-android.png\" alt=\"A synthetic fixture page rendered inside Obsidian on mobile\" width=\"280\"\u003e\n\u003c/p\u003e\n\nThe screenshots use only the synthetic development vault included in this repository.\n\n## Install\n\n### Obsidian community plugins\n\n1. Open **Settings → Community plugins** in Obsidian.\n2. Select **Browse** and search for **HTML Shelf**.\n3. Select **Install**, then **Enable**.\n\n### Manual\n\n1. Download `main.js`, `manifest.json`, and `styles.css` from the latest release.\n2. Put all three files in `\u003cvault\u003e/.obsidian/plugins/html-shelf/`.\n3. Reload Obsidian, then enable **HTML Shelf** under **Settings → Community plugins**.\n\n### Obsidian Sync\n\nObsidian Sync does not sync `.html` and `.htm` files by default. If your HTML\nlibrary is stored on another device, enable **Settings → Sync → Selective\nsync → Sync all other types** on both the source device and every device that\nshould receive the files. This setting is device-specific.\n\nRestart Obsidian after changing the setting; on mobile, force-quit the app and\nreopen it. Wait for Sync to finish before opening HTML Shelf. Also confirm that\nthe library folder is not listed under **Excluded folders** in the Sync settings.\n\n## Usage\n\n- Select the library icon in the ribbon, or run **HTML Shelf: Open shelf** from the command palette.\n- Type in **Filter pages** to search titles, paths, and sections.\n- Select a page to render it inside Obsidian. Relative links to other HTML pages remain inside the plugin; the page bar provides Back and Shelf controls.\n- Long-press a page on mobile, or right-click it on desktop, to open its menu. **Copy path** puts the vault-relative path on the clipboard, and **Delete** removes the file after confirmation. Obsidian's deleted-files preference determines how the file is removed.\n- Open **Settings → HTML Shelf** to include specific folders, exclude subtrees, or hide `.htm` files from the shelf. Changes apply immediately.\n\n`index.html` and `index.htm` files are treated as navigation targets and are not listed on the shelf.\n\n## Optional `html-shelf.json` curation\n\nA folder may contain an `html-shelf.json` file to curate how pages beneath that folder appear:\n\n```json\n{\n  \"title\": \"AI plans\",\n  \"entries\": [\n    {\n      \"path\": \"feedflow/foo-plan.html\",\n      \"title\": \"Foo plan\",\n      \"section\": \"FeedFlow\"\n    },\n    {\n      \"path\": \"readerflow/bar-plan.html\",\n      \"title\": \"Bar plan\",\n      \"section\": \"ReaderFlow\"\n    }\n  ]\n}\n```\n\n- `title` is an optional library display name.\n- `entries` is required. Every entry requires `path` and `title`; `section` is optional.\n- `path` is relative to the folder containing the manifest. Absolute paths and paths containing `..` are rejected.\n- An explicit section is displayed as `\u003clibrary title\u003e · \u003csection\u003e` when the manifest has a title, or simply `\u003csection\u003e` otherwise.\n- An entry without `section` keeps its normal scan-derived section, without the library-title prefix, so it remains grouped with unlisted siblings.\n- Unlisted HTML files still appear normally. A manifest curates; it does not hide files. Index files remain hidden.\n- When nested manifests cover the same file, the deepest manifest wins.\n- Invalid manifests are ignored, normal scanning continues, and Obsidian shows a notice.\n\n## Security\n\nHTML Shelf treats vault HTML as untrusted content. Scripts, event handlers, embedded frames and objects, refresh redirects, executable URLs, remote stylesheets, and inline CSS `@import` rules are removed before rendering. Desktop and Android use a sandboxed iframe without script permission; iOS uses a sanitized, isolated Shadow DOM renderer because its WebView does not reliably support the same iframe navigation behavior.\n\nSome network-capable content remains intentionally supported:\n\n- Remote images and media referenced by a page may load, including tracking pixels.\n- Inline CSS may fetch remote resources through `url()`, including backgrounds, fonts, and cursors.\n- A referenced local CSS file is loaded unmodified and may itself import remote CSS.\n\nThese have the same privacy implications as opening that HTML in a browser. Review HTML from untrusted sources before adding it to your vault.\n\n## Limitations\n\n- Relative links to non-HTML files, such as an image wrapped in an `\u003ca\u003e` element, do not open in the initial release.\n- Relative paths are case-sensitive. A link whose casing differs from the vault file is reported as missing.\n- **Include .htm files** affects the shelf listing only. A `.htm` file opened directly still renders.\n- HTML Shelf does not export or rewrite source files.\n\n## Contributing\n\nIssues and pull requests are welcome. Install Node.js 20 or newer, then run:\n\n```sh\nnpm ci\nnpm run check\n```\n\nUse the synthetic `dev-vault/` fixtures for screenshots, tests, and bug reports. Do not commit content from a personal vault.\n\n## License\n\n[MIT](LICENSE) © 2026 Marco Gomiero\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprof18%2Fhtml-shelf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprof18%2Fhtml-shelf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprof18%2Fhtml-shelf/lists"}