Skip to content

Commit e478adf

Browse files
onmaxonmax
committed
feat: enhance documentation
1 parent c53b533 commit e478adf

File tree

18 files changed

+800
-83
lines changed

18 files changed

+800
-83
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 65 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,115 +2,137 @@ import type { NimiqVitepressThemeConfig } from 'nimiq-vitepress-theme'
22
import type { UserConfig } from 'vitepress'
33
import { defineConfigWithTheme } from 'vitepress'
44
import PreviewPlugin from './theme/plugins/component-preview'
5+
import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
6+
import { createFileSystemTypesCache } from '@shikijs/vitepress-twoslash/cache-fs'
57

68
// @unocss-include
79

810
export default defineConfigWithTheme<NimiqVitepressThemeConfig>({
911
title: 'Nimiq UI',
1012
description: 'Build awesome apps with the Nimiq Style',
11-
base: 'nimiq-ui',
13+
base: '/nimiq-ui/',
1214
themeConfig: {
1315
modules: [
1416
{
15-
subpath: '/nimiq-css',
17+
subpath: 'nimiq-css',
1618
icon: 'i-custom:nimiq-css',
17-
defaultPageLink: '/nimiq-css/getting-started/',
19+
defaultPageLink: '/nimiq-css/getting-started',
1820
text: 'Nimiq CSS',
1921
description: 'The CSS framework',
2022
sidebar: [
2123
{
22-
label: 'Guide',
24+
label: 'Getting Started',
2325
items: [
24-
{ text: 'Getting started', link: '/nimiq-css/getting-started/', icon: 'i-tabler:arrow-guide scale-120' },
25-
{ text: 'Philosophy', link: '/nimiq-css/philosophy/', icon: 'i-tabler:brain scale-120' },
26-
{ text: 'Migrate from Nimiq Style', link: '/nimiq-css/migrate-from-nimiq-styles/', icon: 'i-tabler:arrow-move-right-filled scale-120' },
27-
{ text: 'Palette', link: '/nimiq-css/palette/', icon: 'i-tabler:palette scale-120' },
26+
{ text: 'Getting started', link: '/nimiq-css/getting-started', icon: 'i-tabler:arrow-guide ' },
27+
{ text: 'Philosophy', link: '/nimiq-css/philosophy', icon: 'i-tabler:brain ' },
28+
{ text: 'Migrate from Nimiq Style', link: '/nimiq-css/migrate-from-nimiq-styles', icon: 'i-tabler:arrow-move-right-filled ' },
29+
],
30+
},
31+
{
32+
label: 'Core Features',
33+
items: [
34+
{ text: 'Palette', link: '/nimiq-css/palette', icon: 'i-tabler:palette ' },
35+
{ text: 'Utilities', link: '/nimiq-css/utilities', icon: 'i-tabler:building-factory-2 ' },
36+
{ text: 'Typography', icon: 'i-nimiq:file-text ', items: [
37+
{ text: 'Getting started', link: '/nimiq-css/typography' },
38+
{ text: 'Example', link: '/nimiq-css/typography/demo-article' },
39+
]},
2840
{
2941
text: 'CSS Layers',
30-
icon: 'i-tabler:binary-tree scale-120',
42+
icon: 'i-tabler:binary-tree ',
3143
items: [
32-
{ text: 'Index', link: '/nimiq-css/layers/index/' },
33-
{ text: 'Preflights', link: '/nimiq-css/layers/preflights/' },
34-
{ text: 'Colors', link: '/nimiq-css/layers/colors/' },
35-
{ text: 'Utilities', link: '/nimiq-css/layers/utilities/' },
36-
{ text: 'Typography', link: '/nimiq-css/layers/typography/' },
37-
{ text: 'Static content', link: '/nimiq-css/layers/static-content/' },
44+
{ text: 'Overview', link: '/nimiq-css/layers/index' },
45+
{ text: 'Preflights', link: '/nimiq-css/layers/preflights' },
46+
{ text: 'Colors', link: '/nimiq-css/layers/colors' },
47+
{ text: 'Fonts', link: '/nimiq-css/layers/fonts' },
48+
{ text: 'Utilities', link: '/nimiq-css/layers/utilities' },
49+
{ text: 'Typography', link: '/nimiq-css/layers/typography' },
50+
{ text: 'Static content', link: '/nimiq-css/layers/static-content' },
3851
],
3952
},
40-
],
53+
]
4154
},
55+
{
56+
label: 'Integrations',
57+
items: [
58+
{ text: 'Native CSS', link: '/nimiq-css/integrations/native-css', icon: 'i-simple-icons:css' },
59+
{ text: 'UnoCSS', link: '/nimiq-css/integrations/unocss', icon: 'i-simple-icons:unocss' },
60+
{ text: 'TailwindCSS', link: '/nimiq-css/integrations/tailwindcss', icon: 'i-simple-icons:tailwindcss' },
61+
]
62+
}
4263
],
4364
},
4465
{
45-
subpath: '/frankenstein',
66+
subpath: 'frankenstein',
4667
text: 'Nimiq Frankenstein',
4768
icon: 'i-custom:frankenstein',
4869
defaultPageLink: '/frankenstein/getting-started',
4970
description: 'The Vue 3 components',
5071
sidebar: [
5172
{
52-
label: 'Guide',
73+
label: 'Getting Started',
5374
items: [
54-
{ text: 'Getting started', link: '/frankenstein/getting-started', icon: 'i-tabler:arrow-guide scale-120' },
75+
{ text: 'Getting started', link: '/frankenstein/getting-started', icon: 'i-tabler:arrow-guide ' },
5576
],
5677
},
5778
{
58-
label: 'Components',
79+
label: 'Vue Components',
5980
items: [
6081
{
61-
text: 'Modal',
82+
text: 'Dialog Components',
6283
icon: 'i-custom:modal',
6384
items: [
64-
{ text: 'Basic Modal', link: '/frankenstein/components/basic-modal/' },
65-
{ text: 'Nested Modal', link: '/frankenstein/components/nested-modal/' },
85+
{ text: 'Basic Modal', link: '/frankenstein/components/basic-modal' },
86+
{ text: 'Nested Modal', link: '/frankenstein/components/nested-modal' },
6687
],
6788
},
6889
{
6990
text: 'Animated Staking Ripple',
7091
icon: 'i-nimiq:leaf-3',
71-
link: '/frankenstein/components/animated-staking-ripple/',
92+
link: 'frankenstein/components/animated-staking-ripple',
7293
}
7394
],
7495
},
7596
],
7697
},
7798
{
78-
subpath: '/vitepress-theme',
99+
subpath: 'vitepress-theme',
79100
text: 'Vitepress Theme',
80101
icon: 'i-custom:nimiq-vitepress',
81-
defaultPageLink: '/vitepress-theme/',
102+
defaultPageLink: '/vitepress-theme',
82103
description: 'Your Vitepress with Nimiq',
83104
sidebar: [
84105
{
85106
items: [
86-
{ text: 'Getting started', link: '/vitepress-theme/', icon: 'i-tabler:arrow-guide scale-120' },
107+
{ text: 'Getting Started', link: '/vitepress-theme', icon: 'i-tabler:arrow-guide ' },
87108
{
88-
text: 'Components',
109+
text: 'Available Components',
89110
icon: 'i-nimiq:icons-lg-widget',
90111
items: [
91-
{ text: 'Code Block', link: '/vitepress-theme/components/code-block/' },
92-
{ text: 'Card', link: '/vitepress-theme/components/card/' },
93-
{ text: 'Large Card', link: '/vitepress-theme/components/large-card/' },
94-
{ text: 'Grid', link: '/vitepress-theme/components/grid/' },
95-
{ text: 'Callout & Blockquotes', link: '/vitepress-theme/components/callouts-and-blockquotes/' },
96-
{ text: 'Vitepress Components', link: '/vitepress-theme/components/vitepress-components/' },
112+
{ text: 'Code Block', link: '/vitepress-theme/components/code-block' },
113+
{ text: 'Card', link: '/vitepress-theme/components/card' },
114+
{ text: 'Large Card', link: '/vitepress-theme/components/large-card' },
115+
{ text: 'Grid', link: '/vitepress-theme/components/grid' },
116+
{ text: 'Callout & Blockquotes', link: '/vitepress-theme/components/callouts-and-blockquotes' },
117+
{ text: 'Vitepress Components', link: '/vitepress-theme/components/vitepress-components' },
97118
],
98119
},
99120
],
100121
},
101122
],
102123
},
103124
{
104-
subpath: '/nimiq-icons',
125+
subpath: 'nimiq-icons',
105126
text: 'Nimiq Icons',
106127
icon: 'i-custom:nimiq-vitepress',
107-
defaultPageLink: '/nimiq-icons/',
128+
defaultPageLink: '/nimiq-icons/explorer',
108129
description: 'The Iconify Set for Nimiq',
109130
sidebar: [
110131
{
111132
items: [
112-
{ text: 'Getting started', link: '/nimiq-icons/', icon: 'i-tabler:arrow-guide scale-120' },
113-
{ text: 'Explorer', link: '/nimiq-icons/explorer', icon: 'i-tabler:telescope scale-120' },
133+
{ text: 'Getting started', link: '/nimiq-icons', icon: 'i-tabler:arrow-guide ' },
134+
{ text: 'Explorer', link: '/nimiq-icons/explorer', icon: 'i-tabler:telescope ' },
135+
{ text: 'Figma', link: 'https://www.figma.com/design/iyfVJafk18HfrYLXukpf0n/Nimiq-Icons', icon: 'i-tabler:brand-figma ' },
114136
],
115137
},
116138
],
@@ -126,5 +148,10 @@ export default defineConfigWithTheme<NimiqVitepressThemeConfig>({
126148
},
127149
theme: 'vitesse-dark',
128150
languages: ['vue', 'vue-html', 'js', 'ts', 'markdown'],
151+
codeTransformers: [
152+
transformerTwoslash({
153+
typesCache: createFileSystemTypesCache()
154+
})
155+
],
129156
},
130157
} satisfies UserConfig<NimiqVitepressThemeConfig>)

‎docs/.vitepress/theme/components/ComponentPreview.vue‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { TabsContent, TabsIndicator, TabsList, TabsRoot, TabsTrigger } from 'rek
33
</script>
44

55
<template>
6-
<TabsRoot w-full defaultValue="preview" f-my-lg>
6+
<TabsRoot w-full defaultValue="preview" f-my-lg class="nq-raw">
77
<TabsList relative shrink-0 f-mx-lg flex="~ items-center justify-start gap-x-12" w-max aria-label="See the markdown code and rendered preview">
88
<!-- <TabsIndicator absolute px-8 left-0 h-3 bottom-2 w="$reka-tabs-indicator-size" bg-blue
99
translate-x="$reka-tabs-indicator-position" translate-y-1 transition="[width,transform]"

‎docs/.vitepress/theme/components/IconSet.vue‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,17 @@ function selectColor(c: Color) {
151151
<div size-64 />
152152
</div>
153153
<p f-mt-sm f-text-xs pl-4 text-neutral-800 font-semibold>Select an icon</p>
154+
155+
<div flex="~ items-center gap-12" f-mt-sm>
156+
<button v-for="c in colors" :key="c" shrink-0 size-21 rounded-full outline="~ 1 neutral/20"
157+
:data-active="activeColor === c ? '' : undefined"
158+
:class="{ 'op-30 hocus:op-80': c !== activeColor || (isLogo && !isMono) }" transition-colors
159+
@click="selectColor(c)" :style="`background-color: rgba(var(--nq-${c}));`" />
160+
161+
<button @click="rotateLogoIcon" stack v-if="isLogo" bg="neutral-500 data-active:neutral" text-neutral-0 size-21 transition-opacity aspect-square rounded-full :data-state="!isMono ? 'active' :''">
162+
<span block :class="isMono ? 'i-tabler:paint' : isWhite ? 'i-tabler:paint-off' : !hasWhite ? 'i-nimiq:moon' : 'i-tabler:paint-off'" />
163+
</button>
164+
</div>
154165
</header>
155166
<template v-else>
156167
<header flex="col gap-16 items-start"

‎docs/.vitepress/theme/index.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
import type { EnhanceAppContext, Theme } from 'vitepress'
22
import { Layout } from 'nimiq-vitepress-theme'
33

4+
import '@shikijs/vitepress-twoslash/style.css'
5+
6+
import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
7+
48
import NqCard from 'nimiq-vitepress-theme/components/NqCard.vue'
59

610
import NqGrid from 'nimiq-vitepress-theme/components/NqGrid.vue'
@@ -12,6 +16,8 @@ import 'virtual:uno.css'
1216
export default {
1317
Layout,
1418
enhanceApp({ app }: EnhanceAppContext) {
19+
app.use(TwoslashFloatingVue)
20+
1521
app.component('ComponentPreview', ComponentPreview)
1622

1723
app.component('NqCard', NqCard)

‎docs/frankenstein/components/animated-staking-ripple/index.md‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,12 @@
22

33
<ComponentPreview filePath="./AnimatedStakingRipple.vue">
44

5-
```vue
65
<script setup>
7-
import AnimatedStakingRipple from '@/components/AnimatedStakingRipple.vue';
6+
import AnimatedStakingRipple from './AnimatedStakingRipple.vue';
87
</script>
98

109
<template>
1110
<AnimatedStakingRipple />
1211
</template>
13-
```
14-
1512

1613
</ComponentPreview>

‎docs/nimiq-css/integrations/native-css.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Nimiq CSS in Native CSS
2+
3+
4+
## Fonts
5+
6+
You can use the css file directly in your project but make sure that the paths to the font files are correct. The default path is optimized for Vite.
7+
8+
> [!TIP]
9+
> If you are using `vite`, you should place the fonts inside `/public/assets/fonts/`
10+
11+
```css
12+
import url('nimiq-css/css/fonts.css') @layer nq-fonts;
13+
```
14+
15+
### Manual
16+
17+
You will need to download and place the font files in your project, then you can copy the contents of the `fonts.css` file, modify the paths to the font files and include it in your project.
18+
19+
<<< @/../packages/nimiq-css/src/css/fonts.css

‎docs/nimiq-css/integrations/tailwindcss.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Nimiq CSS in TailwindCSS
2+
3+
Add Nimiq CSS to your TailwindCSS project.
4+
5+
> [!IMPORTANT]
6+
> Unfortunately, Nimiq CSS is not available as a TailwindCSS plugin. However, you can still use Nimiq CSS in your project by doing one of the following:
7+
8+
## Importing the CSS
9+
10+
In your entry CSS file, import the Nimiq CSS file:
11+
12+
::: code-group
13+
14+
```css [v4 | index.css]
15+
@import url('nimiq-css/css/index.css') @layer nq-all;
16+
17+
/* Or if you prefer import specific layers only */
18+
/* @import url('nimiq-css/css/typography.css') @layer nq-typography; */
19+
20+
@import "tailwindcss";
21+
```
22+
23+
```css [v3 | index.css]
24+
@import url('nimiq-css/css/index.css') @layer nq-all;
25+
26+
/* Or if you prefer import specific layers only */
27+
/* @import url('nimiq-css/css/typography.css') @layer nq-typography; */
28+
29+
@tailwind base;
30+
@tailwind components;
31+
@tailwind utilities;
32+
```
33+
:::
34+
35+
36+
> [!CAUTION]
37+
> With this approach, you will be missing a bunch of stuff like the colors or good DX for the utilities.
38+
39+
You can add the missing colors to your theme manually. Check out [colors.css](https://github.com/onmax/nimiq-ui/tree/main/packages/nimiq-css/src/css/colors.css) for the color palette.
40+
41+
## Migrating to UnoCSS
42+
43+
You can think of Tailwind as MacOS and UnoCSS as Linux. They are both great, but they have different philosophies:
44+
45+
| Feature Category | Feature | Tailwind | UnoCSS |
46+
| --- | --- | :---: | :---: |
47+
| **Development** | Developer Experience | 👍 Good | 🚀 Excellent |
48+
| | Build Performance | ⚡️ Amazing (v4) | ⚡️ Amazing |
49+
| **Customization** | Theme Customization | 🔧 Complex | 🎯 Simple |
50+
| | Custom Rules | 🔧 Complex | ✨ Flexible |
51+
| | Preset Extension | 🟡 Limited | 💫 Extensive |
52+
| **Features** | Syntax Options | 📝 Class-based | 🎨 Multiple* |
53+
| | Web Fonts | 🔧 Manual Setup | 🤖 Auto-loading |
54+
| | Icons Support | 🔧 Manual Setup | 🤖 Auto-loading |
55+
| | Dark Mode | ✅ Built-in | ✅ Built-in |
56+
| | Built-in playground | ❌ No | ✅ Yes |
57+
| **Ecosystem** | Community Size | 🌟 Massive | 📈 Growing |
58+
| | Documentation | 📚 Extensive | 📖 Good |
59+
| | Third-party Tools | 🛠️ Abundant | 🔨 Growing |
60+
61+
\* _Including class-based, attributify, pure CSS, and CSS-in-JS_
62+
63+
---
64+
65+
The migration is straightforward: [Install UnoCSS](https://unocss.dev/integrations/) and add the Tailwind preset to your configuration file: [wind4](https://unocss.dev/presets/wind4#wind4-preset) or [wind3](https://unocss.dev/presets/wind3#wind3-preset).
66+
67+
Then, you can start using [Nimiq CSS in UnoCSS](./unocss.md).
68+
69+
## Create a TailwindCSS Plugin
70+
71+
You can create a PR to add Nimiq CSS as a TailwindCSS plugin. Check out the [TailwindCSS documentation](https://tailwindcss.com/docs/plugins) and the [UnoCSS preset implementation](https://github.com/onmax/nimiq-ui/tree/main/packages/nimiq-css/src/unocss/index.ts) for inspiration.
72+

0 commit comments

Comments
 (0)