seemore 1.0.5 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +72 -96
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,11 @@
1
+ <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/vscode/assets/icon.png" alt="seemore" width="96" height="96">
2
+
1
3
  # seemore
2
4
 
3
5
  Let AI write the Markdown. Let seemore show it better.
4
6
 
5
- [![npm version](https://img.shields.io/npm/v/@arifszn%2Fseemore)](https://www.npmjs.com/package/seemore)
7
+ [![npm version](https://img.shields.io/npm/v/seemore)](https://www.npmjs.com/package/seemore)
8
+ [![VS Code Marketplace](https://img.shields.io/badge/VS_Code-Marketplace-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=arifszn.seemore-vscode)
6
9
  [![CI](https://github.com/arifszn/seemore/actions/workflows/ci.yml/badge.svg)](https://github.com/arifszn/seemore/actions/workflows/ci.yml)
7
10
  [![Licence: MIT](https://img.shields.io/badge/Licence-MIT-informational)](LICENSE)
8
11
 
@@ -10,63 +13,87 @@ AI tools write Markdown — specs, notes, guides, READMEs, whole folders of it,
10
13
  anyone can read. A pile of `.md` files is write-only memory: nothing to click, nothing to
11
14
  search, no order.
12
15
 
13
- seemore is the other half. Point it at a folder that already exists and read it in your
14
- browser instead — every file rendered, with navigation, search and a clean reading
15
- layout. You don't move the files, you don't write any code, and there is nothing to set
16
- up.
16
+ seemore points at that folder and renders it as a proper site instead, without you moving a single file or writing any code.
17
+
18
+ Three ways to use it:
19
+
20
+ - **[In your browser](#view-in-your-browser)**: `npx seemore` serves the folder you're standing in and updates live as you edit.
21
+ - **[In VS Code](#view-in-vs-code)**: an extension puts the same site in a panel next to the file you're editing.
22
+ - **[As a static site](#publish-it-to-the-web)**: `npx seemore build` exports plain HTML you can host anywhere, so it doubles as a docs framework, not just a preview tool.
23
+
24
+ ## View in your browser
17
25
 
18
26
  ```bash
19
27
  npx seemore # see the current folder in your browser, live, no setup
28
+ ```
29
+
30
+ Open a terminal in your folder of Markdown files, run `npx seemore`, and open the address it prints (`http://localhost:4040` by default). From there it's live: add, rename, retitle or delete a file and the site updates immediately, navigation included.
31
+
32
+ With no folder given, seemore serves the folder you're standing in. Point it at a subfolder with `npx seemore docs` if that's where your files live.
33
+
34
+ ## View in VS Code
35
+
36
+ Install [seemore for VS Code](https://marketplace.visualstudio.com/items?itemName=arifszn.seemore-vscode) to get the same rendered site as a panel beside your editor. No terminal, no `npx`, no browser tab to manage.
37
+
38
+ 1. Open any Markdown file.
39
+ 2. Click the seemore icon in the editor's title bar, or right-click a folder in the explorer and choose **Open Folder in seemore**.
40
+ 3. The rendered site opens beside your editor, scoped to that file's folder.
41
+
42
+ ### Commands
43
+
44
+ | Command | Where | Does |
45
+ | --- | --- | --- |
46
+ | **Open in seemore** | Editor title bar, on any Markdown file | Renders that file's folder as a site |
47
+ | **Open Folder in seemore** | Explorer, right-click a folder | Renders that folder as a site and pins it as the root |
48
+ | **Pin Current Root** | Status bar item, while a site is open | Pins the currently-serving root for this workspace |
49
+
50
+ ### Settings
51
+
52
+ | Setting | Default | Effect |
53
+ | --- | --- | --- |
54
+ | `seemore.path` | *(bundled copy)* | Path to a `seemore` CLI entry point to use instead of the version bundled with the extension. Leave empty unless you're developing seemore itself. |
55
+
56
+ ## Publish it to the web
57
+
58
+ ```bash
20
59
  npx seemore build # static export to dist/ for any host
21
60
  ```
22
61
 
23
- ## Getting started
62
+ The result is a `dist/` folder of plain web files: drop it on [Netlify](https://netlify.com), [Surge](https://surge.sh), [Cloudflare Pages](https://pages.cloudflare.com) or [GitHub Pages](https://pages.github.com), or hand it to any web host. Every page is its own file, so deep links and reloads work everywhere without special host rules. seemore also writes the handful of files individual hosts look for:
63
+
64
+ | File | Read by |
65
+ | --- | --- |
66
+ | `404.html` | GitHub Pages, Netlify, Cloudflare Pages, Vercel, S3 |
67
+ | `_redirects` | Netlify, Cloudflare Pages |
68
+ | `200.html` | Surge |
69
+ | `.nojekyll` | GitHub Pages, so Jekyll doesn't drop every path starting with `_` |
70
+
71
+ None of these are required for a host that isn't listed above. If your host serves a folder of files, it serves a seemore build.
24
72
 
25
- 1. Open a terminal in your folder of Markdown files.
26
- 2. Run `npx seemore`, then open the address it prints —
27
- `http://localhost:4040` by default — in your browser.
73
+ **GitHub Pages, one thing to know:** project sites live at `username.github.io/my-repo/`, not at the root. Tell seemore once:
28
74
 
29
- From there it's live: every file you add, rename, retitle or delete is reflected
30
- immediately, navigation included. When you're happy, `npx seemore build`
31
- produces a folder
32
- of ordinary web files you can put on any host (more on that under
33
- [Publishing](#publishing)).
75
+ ```ts
76
+ export default defineConfig({ base: '/my-repo/' });
77
+ ```
34
78
 
35
- With no folder given, seemore serves the folder you are standing in. Point it at a
36
- subfolder with `npx seemore docs` if that's where your files live.
79
+ or `seemore build --base /my-repo/`. Under GitHub Actions with no `base` set, the build prints the exact line to add.
37
80
 
38
81
  ## What you get by default
39
82
 
40
- - **Real pages in your browser, not a placeholder.** Every page arrives with its full
41
- text already in it — nothing waits on JavaScript, and what you see is what a search
42
- engine sees. A test asserts it.
43
- - **Fast, app-like browsing.** Pages start loading when you point at a link, and page
44
- changes animate smoothly — without giving up the plain-files output above.
45
- - **A preview that keeps up.** Add, rename, retitle, reorder or delete a file and the
46
- site updates instantly — no restart, no full page reload.
47
- - **Search built in.** The whole site is searchable out of the box, with no server to run
48
- and nothing to pay for. If your site grows past what a no-server search can carry, the
49
- build says so and points at the alternatives.
50
- - **Sub-folder sites that work.** If your site lives at `example.com/my-repo/` instead of
51
- the root, set `base` once and links, search and assets all follow. A test builds the
52
- site under a sub-folder and asserts nothing leaks.
53
- - **Publish anywhere.** The build is a folder of ordinary files — no special server
54
- setup. The few conventions individual hosts look for are written for you.
83
+ Every page arrives with its full text already in it, no placeholder or loading skeleton. Pages start loading as soon as you point at a link, and page transitions animate, without giving up the plain-files output above. Add, rename, retitle, reorder or delete a file and the running preview updates immediately: no restart, no full reload.
84
+
85
+ Search works out of the box with no server to run and nothing to pay for; if your site grows past what a no-server search index can carry, the build tells you and points at alternatives. If your site lives under a path like `example.com/my-repo/` rather than the root, set `base` once and links, search and assets all follow (a test builds the site under a sub-folder and checks nothing leaks). Since the build is just ordinary files, publishing means dropping that folder on any host; the few conventions individual hosts look for are written for you automatically.
55
86
 
56
87
  ## Content
57
88
 
58
- `.md` and `.mdx` alike, with the format inferred per file, so plain Markdown never needs
59
- MDX syntax.
89
+ `.md` and `.mdx` alike, with the format inferred per file, so plain Markdown never needs MDX syntax.
60
90
 
61
- - GitHub Flavoured Markdown, admonitions (note / tip / warning boxes), step-by-step
62
- lists, and colour-highlighted code blocks
63
- - `[[wikilinks]]`, including `[[Page|label]]` and `[[Page#Heading]]` — the easiest way
64
- for you or your AI to link pages, with no relative paths to get right
91
+ - GitHub Flavoured Markdown, admonitions (note / tip / warning boxes), step-by-step lists, and colour-highlighted code blocks
92
+ - `[[wikilinks]]`, including `[[Page|label]]` and `[[Page#Heading]]`, the easiest way for you or your AI to link pages without relative paths to get right
65
93
  - Relative `.md` links are resolved to working links automatically
66
94
  - Mermaid diagrams, rendered in the browser
67
95
  - Sibling images inlined as hashed assets, sibling PDFs open in the browser's own viewer
68
- - Frontmatter (the `key: value` block at the top of a file) is validated, with errors
69
- that name the file and the field
96
+ - Frontmatter (the `key: value` block at the top of a file) is validated, with errors that name the file and the field
70
97
 
71
98
  ### Page addresses
72
99
 
@@ -90,8 +117,7 @@ Pages are ordered by:
90
117
 
91
118
  ## Configuration
92
119
 
93
- Optional. A folder with no config file builds correctly. If you want to adjust things,
94
- create `seemore.config.ts` next to your content:
120
+ Optional. A folder with no config file builds correctly in the browser, in VS Code, and when built for publishing. If you want to adjust things, create `seemore.config.ts` next to your content:
95
121
 
96
122
  ```ts
97
123
  // seemore.config.ts
@@ -115,15 +141,11 @@ export default defineConfig({
115
141
 
116
142
  ### Themes
117
143
 
118
- Eleven built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dusk`,
119
- `ocean`, `purple`, `ruby`, `solar`, `aspen`, `emerald`, `shadcn`. For anything else, put
120
- your own CSS in `css` — it is appended last and wins. Dark and light follow your system
121
- setting, with a toggle that remembers your choice.
144
+ Eleven built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dusk`, `ocean`, `purple`, `ruby`, `solar`, `aspen`, `emerald`, `shadcn`. For anything else, put your own CSS in `css`; it's appended last, so it wins. Dark and light follow your system setting, with a toggle that remembers your choice.
122
145
 
123
146
  ### Features
124
147
 
125
- A flat list of switches for readers who want fine control. Prefix one with `!` to switch
126
- off something that is on by default.
148
+ A flat list of switches for readers who want fine control. Prefix one with `!` to switch off something that's on by default.
127
149
 
128
150
  | Flag | Default | Effect |
129
151
  | --- | --- | --- |
@@ -142,43 +164,9 @@ off something that is on by default.
142
164
  | `search.highlight` | on | Highlight the query on the page you land on |
143
165
  | `social.cards` | off | Per-page OG images (needs `takumi-js`) |
144
166
 
145
- Combinations that cannot work are a config error naming both flags and the fix.
167
+ Combinations that can't work together raise a config error naming both flags and the fix.
146
168
 
147
- ## Publishing
148
-
149
- ```bash
150
- npx seemore build
151
- ```
152
-
153
- The result is a `dist/` folder of plain web files — drop it on
154
- [Netlify](https://netlify.com), [Surge](https://surge.sh),
155
- [Cloudflare Pages](https://pages.cloudflare.com) or
156
- [GitHub Pages](https://pages.github.com), or hand it to any web host. Every page is its
157
- own file, so no host needs special rules to serve a deep link, and reloading after moving
158
- around the site works everywhere. Alongside the pages, seemore writes the few conventions
159
- individual hosts look for:
160
-
161
- | File | Read by |
162
- | --- | --- |
163
- | `404.html` | GitHub Pages, Netlify, Cloudflare Pages, Vercel, S3 |
164
- | `_redirects` | Netlify, Cloudflare Pages |
165
- | `200.html` | Surge |
166
- | `.nojekyll` | GitHub Pages — without it, Jekyll drops every path starting with `_` |
167
-
168
- None of these are required for a host that is not listed. If yours serves a folder of
169
- files, it serves a seemore build.
170
-
171
- **GitHub Pages, one thing to know:** project sites live at
172
- `username.github.io/my-repo/`, not at the root. Tell seemore once:
173
-
174
- ```ts
175
- export default defineConfig({ base: '/my-repo/' });
176
- ```
177
-
178
- or `seemore build --base /my-repo/`. Under GitHub Actions with no `base` set, the build
179
- prints the exact line to add.
180
-
181
- ## Command reference
169
+ ## CLI reference
182
170
 
183
171
  ```
184
172
  seemore [dir] start the live preview
@@ -192,21 +180,9 @@ seemore build [dir] static export into dist/
192
180
  --base <path> subpath the site is served from
193
181
  ```
194
182
 
195
- ## What seemore is not
196
-
197
- seemore shows folders of Markdown in your browser and exports them for hosting — that's
198
- all it does. It is not a general site builder, not a CMS, and not a place to build
199
- custom web apps.
200
- Multi-version docs, translations, and opening the site by double-clicking a file on disk
201
- are out of scope.
202
-
203
183
  ## Under the hood
204
184
 
205
- Built in the open on open tools: [fumadocs](https://fumadocs.vercel.app) provides the
206
- interface presets, with [Shiki](https://shiki.style), [Mermaid](https://mermaid.js.org),
207
- [Vite](https://vite.dev) and [React Router](https://reactrouter.com) underneath. Bug
208
- reports and pull requests are welcome at
209
- [github.com/arifszn/seemore](https://github.com/arifszn/seemore).
185
+ [fumadocs](https://fumadocs.vercel.app) provides the interface presets, with [Shiki](https://shiki.style), [Mermaid](https://mermaid.js.org), [Vite](https://vite.dev) and [React Router](https://reactrouter.com) underneath. The VS Code extension runs the same CLI as a child process it manages. Bug reports and pull requests are welcome at [github.com/arifszn/seemore](https://github.com/arifszn/seemore).
210
186
 
211
187
  ## Licence
212
188
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "seemore",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "Let AI write the Markdown. Let seemore show it better — see any folder of Markdown rendered in your browser, zero config.",
5
5
  "license": "MIT",
6
6
  "type": "module",