Skip to content

Commit 20dbbd9

Browse files
zeejerszeejers
authored
Merge pull request #9 from QuickFlo/development
1.1.0
2 parents 076e0f8 + b4104ae commit 20dbbd9

64 files changed

Lines changed: 10444 additions & 1544 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
27+
- name: Setup pnpm
28+
uses: pnpm/action-setup@v4
29+
with:
30+
version: 10
31+
32+
- name: Setup Node
33+
uses: actions/setup-node@v4
34+
with:
35+
node-version: 20
36+
cache: pnpm
37+
38+
- name: Setup Pages
39+
uses: actions/configure-pages@v4
40+
41+
- name: Install dependencies
42+
run: pnpm install --frozen-lockfile
43+
44+
- name: Build docs
45+
run: pnpm docs:build
46+
47+
- name: Upload artifact
48+
uses: actions/upload-pages-artifact@v3
49+
with:
50+
path: docs/.vitepress/dist
51+
52+
deploy:
53+
environment:
54+
name: github-pages
55+
url: ${{ steps.deployment.outputs.page_url }}
56+
needs: build
57+
runs-on: ubuntu-latest
58+
name: Deploy
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
node_modules
22
dist
3-
*.log
3+
.DS_Store
4+
docs/.vitepress/dist
5+
docs/.vitepress/cache
46
.DS_Store
57
coverage
68
.vscode

‎DOCS_SETUP.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# QuickForms Documentation Setup
2+
3+
✅ **Complete VitePress documentation site created!**
4+
5+
## What's Been Set Up
6+
7+
### 1. VitePress Installation & Configuration
8+
- ✅ VitePress and Vue installed as dev dependencies
9+
- ✅ Beautiful purple-themed configuration with custom branding
10+
- ✅ Full-text search enabled
11+
- ✅ Dark mode support
12+
- ✅ Mobile responsive design
13+
- ✅ Automatic sidebar navigation
14+
15+
### 2. Documentation Structure
16+
17+
```
18+
docs/
19+
├── .vitepress/
20+
│ ├── config.mts # VitePress configuration
21+
│ └── theme/
22+
│ ├── index.ts # Theme setup
23+
│ └── custom.css # Custom purple branding
24+
├── guide/ # User guides
25+
│ ├── what-is-quickforms.md ✅ Complete
26+
│ ├── getting-started.md ✅ Complete
27+
│ ├── comparison.md ✅ Complete
28+
│ ├── schema-basics.md ✅ Complete
29+
│ ├── field-types.md ✅ Stub
30+
│ ├── validation.md ✅ Stub
31+
│ ├── complex-types.md 📝 TODO
32+
│ ├── custom-components.md 📝 TODO
33+
│ ├── theming.md 📝 TODO
34+
│ ├── custom-validators.md 📝 TODO
35+
│ ├── i18n.md 📝 TODO
36+
│ └── rbac.md 📝 TODO
37+
├── api/ # API reference
38+
│ ├── form-options.md ✅ Complete
39+
│ ├── components.md 📝 TODO
40+
│ ├── composables.md 📝 TODO
41+
│ ├── schema-extensions.md 📝 TODO
42+
│ └── testers-registry.md 📝 TODO
43+
├── examples/ # Examples
44+
│ ├── basic-form.md ✅ Complete
45+
│ ├── nested-objects.md 📝 TODO
46+
│ ├── arrays.md 📝 TODO
47+
│ ├── conditional-fields.md 📝 TODO
48+
│ ├── custom-validation.md 📝 TODO
49+
│ └── theming.md 📝 TODO
50+
├── packages/ # Package docs
51+
│ ├── core.md 📝 TODO
52+
│ ├── vue.md 📝 TODO
53+
│ └── quasar.md 📝 TODO
54+
├── public/ # Static assets
55+
├── index.md ✅ Homepage complete
56+
└── README.md ✅ Setup instructions
57+
```
58+
59+
### 3. Scripts Added to package.json
60+
61+
```json
62+
{
63+
"docs:dev": "vitepress dev docs", // Start dev server
64+
"docs:build": "vitepress build docs", // Build for production
65+
"docs:preview": "vitepress preview docs" // Preview production build
66+
}
67+
```
68+
69+
### 4. GitHub Actions Deployment
70+
- ✅ Workflow file created: `.github/workflows/deploy-docs.yml`
71+
- ✅ Automatically deploys to GitHub Pages on push to main
72+
- ✅ Manual deployment trigger available
73+
74+
### 5. Content Migrated from README
75+
76+
The following content has been extracted and organized from your main README:
77+
78+
- **Homepage** - Hero section with features and quick example
79+
- **What is QuickForms** - Philosophy and use cases
80+
- **Getting Started** - Installation and first form tutorial
81+
- **Comparison** - Detailed comparison with JSONForms
82+
- **Schema Basics** - JSON Schema fundamentals
83+
- **Form Options API** - Complete API reference
84+
- **Basic Example** - Working code example with explanations
85+
86+
## Usage
87+
88+
### Development
89+
90+
```bash
91+
# Start local dev server (with hot reload)
92+
pnpm docs:dev
93+
94+
# Opens at http://localhost:5175 (or next available port)
95+
```
96+
97+
### Build & Preview
98+
99+
```bash
100+
# Build for production
101+
pnpm docs:build
102+
103+
# Preview production build
104+
pnpm docs:preview
105+
```
106+
107+
### Deploy to GitHub Pages
108+
109+
1. **Enable GitHub Pages** in your repository settings:
110+
- Go to Settings → Pages
111+
- Source: GitHub Actions
112+
113+
2. **Push to main branch** - The workflow will automatically build and deploy
114+
115+
3. **Your docs will be live at:**
116+
- `https://<username>.github.io/<repo-name>/`
117+
- Example: `https://quickflo.github.io/quickforms/`
118+
119+
## Next Steps
120+
121+
### Content to Add
122+
123+
The following pages are stubbed out or need to be created:
124+
125+
#### High Priority
126+
1. **`guide/complex-types.md`** - Nested objects, arrays, oneOf/anyOf/allOf
127+
2. **`guide/custom-validators.md`** - Sync/async validation examples
128+
3. **`guide/theming.md`** - CSS variables and styling guide
129+
4. **`api/schema-extensions.md`** - Document all `x-*` attributes
130+
131+
#### Medium Priority
132+
5. **`api/components.md`** - DynamicForm, field components reference
133+
6. **`api/composables.md`** - useFormField, useFormContext docs
134+
7. **`examples/nested-objects.md`** - Working example
135+
8. **`examples/arrays.md`** - Working example
136+
9. **`examples/conditional-fields.md`** - oneOf/anyOf examples
137+
138+
#### Lower Priority
139+
10. **`guide/custom-components.md`** - Component registry and testers
140+
11. **`guide/i18n.md`** - Internationalization guide
141+
12. **`guide/rbac.md`** - Role-based access control
142+
13. **`api/testers-registry.md`** - Tester system reference
143+
14. **Package docs** - core.md, vue.md, quasar.md
144+
145+
### Extracting Content from README
146+
147+
Your main README is quite comprehensive. Consider extracting these sections:
148+
149+
- **Validation section** → `guide/validation.md` (partially done)
150+
- **Complex types examples** → `guide/complex-types.md`
151+
- **Custom validators section** → `guide/custom-validators.md`
152+
- **Theming section** → `guide/theming.md`
153+
- **RBAC section** → `guide/rbac.md`
154+
- **i18n section** → `guide/i18n.md`
155+
- **Supported JSON Schema features** → `api/schema-extensions.md`
156+
157+
### Updating the Main README
158+
159+
Once docs are complete, simplify the main README to:
160+
- Brief introduction
161+
- Quick install and example
162+
- Link to full documentation
163+
- Contributing guidelines
164+
- License
165+
166+
## Features
167+
168+
### What Works Out of the Box
169+
170+
- ✅ **Beautiful UI** - Purple-themed, modern design
171+
- ✅ **Search** - Full-text search across all docs
172+
- ✅ **Code highlighting** - Syntax highlighting for Vue, TypeScript, etc.
173+
- ✅ **Code groups** - Tab-based code examples (pnpm/npm/yarn)
174+
- ✅ **Navigation** - Automatic sidebar and page navigation
175+
- ✅ **Mobile responsive** - Works great on all devices
176+
- ✅ **Dark mode** - Automatic theme switching
177+
- ✅ **Fast** - Built with Vite, instant HMR
178+
179+
### Customization Options
180+
181+
The theme is already customized with QuickForms branding:
182+
- Purple color scheme (`#8b5cf6`)
183+
- Custom hero gradient
184+
- QuickForms logo support (add `docs/public/logo.svg`)
185+
186+
To further customize, edit:
187+
- `docs/.vitepress/config.mts` - Site configuration
188+
- `docs/.vitepress/theme/custom.css` - Styling
189+
190+
## Assets
191+
192+
Add the following assets to `docs/public/`:
193+
- `logo.svg` - QuickForms logo for navigation
194+
- Copy `docs/assets/banner.readme.1280x320.png` to `docs/public/assets/` for homepage
195+
196+
## Tips
197+
198+
1. **Keep README concise** - Now that you have docs, the README can be much shorter
199+
2. **Link to docs** - Add a prominent "Documentation" link in README
200+
3. **Use VitePress features**:
201+
- `::: warning` / `::: tip` / `::: danger` callouts
202+
- Code groups for multi-language examples
203+
- Custom components in markdown
204+
4. **Test examples** - Make sure all code examples actually work
205+
5. **Internal linking** - Use relative paths: `[Link](/guide/page)`
206+
207+
## Maintenance
208+
209+
- Update VitePress: `pnpm add -D vitepress@latest`
210+
- Check for broken links: VitePress has built-in dead link checking
211+
- Review analytics: Consider adding Google Analytics or similar
212+
213+
---
214+
215+
**Your docs are ready to go! 🚀**
216+
217+
Run `pnpm docs:dev` to see them in action.

0 commit comments

Comments
 (0)