Skip to content

Commit 130e6fc

Browse files
webJosewebJose
authored
feat(docs): Create docs website (#3)
1 parent 8a914b0 commit 130e6fc

10 files changed

Lines changed: 566 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,17 @@
88
```bash
99
npm install mdsvex-table
1010
```
11-
2. If you don't have an MDSvex layout component configured, add one:
11+
2. If you don't have an MDsveX layout component configured, add one:
1212
```ts
1313
preprocess: [mdsvex({
1414
extensions: ['.svx', '.md'],
1515
layout: join(__dirname, './src/routes/MdLayout.svelte') // Or whatever you wish
1616
})],
1717
```
18-
3. Re-export all table components from `mdsvex-table` in the layout(s) component(s) as per MDSvex's instructions:
18+
3. Re-export all table components in `mdsvex-table` from the layout(s) component(s) as per MDsveX's [instructions](https://mdsvex.pngwn.io/docs#layout):
1919
```svelte
2020
<script lang="ts" module>
21-
// export * ... doesn't work. :-(
21+
// export * ... doesn't work. 😢
2222
export {
2323
table,
2424
thead,

‎src/routes/+layout.svelte‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,24 @@
11
<script lang="ts">
2-
import type { LayoutProps } from './$types';
2+
import type { LayoutProps } from './$types.js';
33
import './app.css';
4+
import Navbar from './Navbar.svelte';
45
5-
let { data, children }: LayoutProps = $props();
6+
type Props = LayoutProps & {
7+
title?: string;
8+
description?: string;
9+
}
10+
11+
let { title, description, children }: Props = $props();
612
</script>
713

8-
<main class="content m-5">
9-
{@render children()}
10-
</main>
14+
<svelte:head>
15+
<title>{title || 'mdsvex-table'}</title>
16+
<meta name="description" content={description || 'mdsvex-table'} />
17+
</svelte:head>
18+
19+
<Navbar />
20+
<div class="container">
21+
<main class="content m-5">
22+
{@render children()}
23+
</main>
24+
</div>

‎src/routes/+page.md‎

Lines changed: 91 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,98 @@
11
---
2-
title: Test Of mdsvex-table
2+
title: mdsvex-table
3+
description: |
4+
Full documentation for mdsvex-table, an NPM package for Svelte web applications that renders a responsive table out of tables generated with the popular mdsvex package and Markdown documents.
35
---
4-
# {title}
56

67
<script>
78
import { CirclePlus } from '@lucide/svelte';
89
</script>
910

10-
| Item | <CirclePlus size="1.1em" /> Description |
11-
| - | - |
12-
| Alpha 1 | Lorem ipsum dolor sit amet, consectetur adipisicing elit. Reiciendis eius assumenda in deleniti recusandae fugiat suscipit iusto ipsam vitae consequuntur quas ex, incidunt, amet corrupti quam veritatis doloremque itaque nostrum cum. Repudiandae, fugit consequatur? Qui laborum ea expedita debitis mollitia repellat ex nam ab earum facere veritatis delectus, voluptate praesentium?|
13-
| Beta 2 | Lorem ipsum dolor sit amet consectetur adipisicing elit. Nemo, ipsum ad voluptate exercitationem corrupti voluptates fugiat qui culpa vero totam? |
14-
| Gamma 3 | [CollageJS](https://collagejs.dev) |
11+
# {title}
12+
13+
This is a Svelte v5 NPM package that provides replacement Svelte components for the necessary HTML elements that compose a table: `table`, `thead`, `tbody`, `tr`, `th` and `td`. These are the ones that can be generated out of a Markdown table. Replacements for `caption` and `tfooter` are not provided. The components are designed to exchange the table markup with list markup (not `ul/ol`, but a list of containers) that can be read better in small devices. In other words: Transforms table to a vertical list of card-like items.
14+
15+
## How It Works
16+
17+
Since this is a component meant to replace Markdown-generated tables, it doesn't rely on component properties. Instead, configuration and all interconnection between the various table components is done through context.
18+
19+
We also don't use the components directly under normal circumstances. Instead, we configure a layout component in *MDsveX* and follow their instructions on how to export all the table-related components.
20+
21+
We finally initialize the whole thing by creating the "root" table context that will apply to all tables in the Markdown document.
22+
23+
These would be the additions to the layout component:
24+
25+
```svelte
26+
<script lang="ts" module>
27+
// export * ... doesn't work. 😢
28+
export {
29+
table,
30+
thead,
31+
tbody,
32+
tr,
33+
th,
34+
td
35+
} from 'mdsvex-table';
36+
</script>
37+
<script lang="ts">
38+
import { setTableContext, TableContext } from 'mdsvex-table';
39+
40+
setTableContext(new TableContext({ /* options */ }));
41+
</script>
42+
```
43+
44+
## Options
45+
46+
| Option | Type | Default | Description |
47+
| - | - | - | - |
48+
| `breakpoint` | `string \| number \| (() => string)` | `576` | The breakpoint at which the list format kicks in. If it is a number, it is assumed to be in pixels; if it is a string (such as `'25rem'`) then it is given as-is to the media query; if it is a function, it must return the entire media query. |
49+
| `ssrBehavior` | `"list" \| "table"` | `'table'` | For Sveltekit and SSR-rendered implementations, it determines how the table will be rendered.
50+
51+
## Styling
52+
53+
For the table, continue styling it the way you've been doing it.
54+
55+
For the list version, this is how it can be styled:
56+
57+
```css
58+
[data-mdsvex-table="table"] {
59+
/* styles */
60+
}
61+
62+
[data-mdsvex-table="tbody"] {
63+
/* styles */
64+
}
65+
66+
[data-mdsvex-table="tr"] {
67+
/* styles */
68+
}
69+
70+
[data-mdsvex-table="th"] {
71+
/* styles */
72+
}
73+
74+
[data-mdsvex-table="td"] {
75+
/* styles */
76+
}
77+
```
78+
79+
Yes, there's also an element that can be targeted with `[data-mdsvex-table="thead"]`, but said element is invisible. It exists only for screen readers, so don't mess with it.
80+
81+
## Development Tips
82+
83+
To improve SSR guessing, 2 easy methods come to mind:
84+
85+
1. Examine the *User Agent* string and determine if the requestor is using a mobile device.
86+
2. Save and send a cookie with the user's `window.innerWidth` value. Then SSR can be 100% accurate after one visit to your web application.
87+
88+
For #1 above, ask an AI and you shall receive recommendations:
89+
90+
| Package | Features | Use Case |
91+
| --- | --- | --- |
92+
| **ua-parser-js** | Widely used, lightweight (~17KB minified). Parses browser, OS, device, CPU, and engine. Works in Node.js when you pass ``req.headers['user-agent']``. | General-purpose parsing with broad ecosystem support. |
93+
| **ua-parser-modern** | TypeScript-native, modular functions (``parseBrowser``, ``parseOS``, etc.). Compatible with modern bundlers (Vite, Rollup, esbuild). Handles tricky cases like Brave spoofing Chrome. | Ideal for TypeScript projects or modern toolchains. |
94+
| **browser-dtector** | Simple API, supports both Node.js and browser. Returns parsed info including platform, version, and flags (``isMobile``, ``isDesktop``, etc.). | Quick detection with minimal setup, good for middleware. |
95+
96+
**IMPORTANT:** I did not sanitize the recommendations, so do that yourself and [tell us about it](https://github.com/WJSoftware/mdsvex-table/discussions) if you like.
97+
98+
As for #2, remember to use [`<svelte:window>`](https://svelte.dev/docs/svelte/svelte-window) to keep the cookie reactively up-to-date.

‎src/routes/MdLayout.svelte‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import { setTableContext, TableContext } from "$lib/table-context.svelte.js";
66
import type { Snippet } from 'svelte';
77
import './md.css';
8+
import { setMdTableContext } from './md-table-context.js';
89
910
type Props = {
1011
children?: Snippet;
@@ -14,8 +15,9 @@
1415
children
1516
}: Props = $props();
1617
17-
// svelte-ignore state_referenced_locally
1818
const tableCtx = setTableContext(new TableContext());
19+
setMdTableContext(tableCtx);
20+
console.log('Table context set.');
1921
</script>
2022

2123
{@render children?.()}

‎src/routes/Navbar.svelte‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
<script lang="ts">
2+
import { resolve } from '$app/paths';
3+
4+
let menuIsActive = $state(false);
5+
</script>
6+
7+
<nav class="navbar">
8+
<div class="container">
9+
<div class="navbar-brand">
10+
<div class="navbar-item navbar-title">mdsvex-table</div>
11+
<button
12+
type="button"
13+
class={["navbar-burger", menuIsActive && "is-active"]}
14+
aria-label="menu"
15+
aria-expanded={menuIsActive}
16+
onclick={() => (menuIsActive = !menuIsActive)}
17+
>
18+
<span aria-hidden="true"></span>
19+
<span aria-hidden="true"></span>
20+
<span aria-hidden="true"></span>
21+
<span aria-hidden="true"></span>
22+
</button>
23+
</div>
24+
<div class={["navbar-menu", menuIsActive && "is-active"]}>
25+
<div class="navbar-start">
26+
<a
27+
class="navbar-item"
28+
href={resolve('/')}
29+
>
30+
Docs
31+
</a>
32+
<a
33+
class="navbar-item"
34+
href={resolve('/demo')}
35+
>
36+
Examples
37+
</a>
38+
</div>
39+
<div class="navbar-end">
40+
<a href="https://mdsvex.pngwn.io/" class="navbar-item">
41+
MDsveX
42+
</a>
43+
<div class="navbar-item">
44+
<a
45+
class="button is-black"
46+
href="https://github.com/WJSoftware/mdsvex-table"
47+
>
48+
<img
49+
src="https://github.githubassets.com/favicons/favicon-dark.svg"
50+
alt="github"
51+
style="width: 1.1em; height: 1.1em;"
52+
/>
53+
</a>
54+
</div>
55+
</div>
56+
</div>
57+
</div>
58+
</nav>
59+
60+
<style>
61+
.navbar-title {
62+
font-weight: bold;
63+
font-size: 1.5rem;
64+
}
65+
</style>

‎src/routes/app.css‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
@import 'https://cdn.jsdelivr.net/npm/bulma@latest/css/bulma.min.css';
1+
@import url('https://cdn.jsdelivr.net/npm/bulma@latest/css/bulma.min.css') layer(Bulma);

0 commit comments

Comments
 (0)