Skip to content

Commit f9b566e

Browse files
marioserrano09marioserrano09
committed
Add comprehensive GitHub Copilot instructions for DynamiaTools website
1 parent 4949cce commit f9b566e

1 file changed

Lines changed: 231 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# GitHub Copilot Instructions for DynamiaTools Website
2+
3+
## Project Overview
4+
5+
This is the official documentation website for **DynamiaTools** (https://dynamia.tools), a full-stack Java 25 framework for building enterprise web applications powered by Spring Boot 4, ZK 10 and frontend libraries.
6+
7+
The website is built using:
8+
- **Astro** (v5.17.2+) - Static site generator
9+
- **Starlight** (v0.37.6+) - Documentation theme for Astro
10+
- **TypeScript** (v5.5.4+)
11+
- **MDX** - For content with React components
12+
13+
## Project Structure
14+
15+
```
16+
website/
17+
├── src/
18+
│ ├── content/
19+
│ │ ├── docs/ # English documentation
20+
│ │ │ ├── index.mdx # Homepage
21+
│ │ │ ├── getting-started.mdx
22+
│ │ │ ├── key-concepts.mdx
23+
│ │ │ ├── custom-setup.mdx
24+
│ │ │ ├── history.mdx
25+
│ │ │ ├── guides/ # Tutorial guides
26+
│ │ │ └── es/ # Spanish translations
27+
│ │ └── config.ts # Content collections config
28+
│ ├── assets/ # Images and static assets
29+
│ └── styles/
30+
│ └── custom.css # Custom theme styles
31+
├── public/ # Static files (favicon, CNAME, etc.)
32+
├── astro.config.mjs # Astro & Starlight configuration
33+
├── package.json
34+
└── tsconfig.json
35+
```
36+
37+
## Key Configuration
38+
39+
### Framework Version
40+
- Current DynamiaTools version is defined in `astro.config.mjs` as `dynamiaToolsVersion`
41+
- When updating framework version, update this constant
42+
43+
### Site Configuration
44+
- Production URL: `https://dynamia.tools`
45+
- Local dev server: `http://localhost:4321`
46+
47+
### Internationalization
48+
- Primary language: English (root)
49+
- Supported translations: Spanish (es)
50+
- Add new translations by creating corresponding folders in `src/content/docs/`
51+
52+
## Content Guidelines
53+
54+
### Documentation Files
55+
All documentation files should:
56+
1. Be written in **MDX format** (`.mdx` extension)
57+
2. Include frontmatter with `title` and `description`
58+
3. Use Starlight components for enhanced UI:
59+
- `Card` and `CardGrid` for feature highlights
60+
- `Aside` for callouts and notes
61+
- `LinkButton` for prominent links
62+
- `Code` for syntax highlighting
63+
64+
### Code Examples
65+
When writing code examples for DynamiaTools:
66+
- Use **Java 25** syntax and features
67+
- Include relevant **Spring Boot 4** annotations
68+
- Show **JPA/Jakarta Persistence** annotations (not javax.*)
69+
- Reference **ZK 10** components when applicable
70+
- Include package declarations and imports
71+
- Add comments to explain key concepts
72+
73+
Example format:
74+
```java
75+
//Contact.java
76+
package demo;
77+
78+
import jakarta.persistence.Entity;
79+
import jakarta.persistence.Id;
80+
import jakarta.validation.constraints.NotEmpty;
81+
82+
@Entity
83+
public class Contact {
84+
@Id
85+
private Long id;
86+
87+
@NotEmpty
88+
private String name;
89+
}
90+
```
91+
92+
### View Descriptors
93+
When documenting view descriptors:
94+
- Use YAML format
95+
- Include file path comments
96+
- Show minimal and extended examples
97+
- Explain required vs optional fields
98+
99+
Example:
100+
```yaml
101+
# /resources/META-INF/descriptors/ContactForm.yml
102+
view: form
103+
beanClass: demo.Contact
104+
autofields: true
105+
```
106+
107+
### Framework Concepts to Document
108+
Key DynamiaTools concepts to explain clearly:
109+
- **Modules** and ModuleProvider
110+
- **Pages** and PageGroups
111+
- **Navigation** system
112+
- **Entities** (JPA)
113+
- **CRUD operations** with CrudService
114+
- **View Descriptors** (forms, tables)
115+
- **Actions** and ActionEvent
116+
- **Templates** and themes
117+
118+
## Styling
119+
120+
### Custom Theme
121+
- Primary accent color: `hsl(150, 76%, 34%)` (green)
122+
- Custom styles in `src/styles/custom.css`
123+
- Use CSS variables from Starlight theme
124+
- Support both light and dark modes
125+
126+
### Component Usage
127+
Prefer using Starlight's built-in components:
128+
```jsx
129+
import {Card, CardGrid, Aside, LinkButton} from '@astrojs/starlight/components';
130+
```
131+
132+
## Translation Guidelines
133+
134+
When adding or updating translations:
135+
1. Create corresponding folder structure in `src/content/docs/[lang]/`
136+
2. Mirror the English structure
137+
3. Update sidebar translations in `astro.config.mjs`
138+
4. Keep frontmatter structure consistent
139+
5. Translate all text content but keep code examples readable
140+
141+
Spanish translation example in sidebar:
142+
```javascript
143+
{
144+
label: 'Start Here',
145+
translations: {
146+
'es': 'Comienza Aquí'
147+
},
148+
items: [...]
149+
}
150+
```
151+
152+
## Development Commands
153+
154+
```bash
155+
npm install # Install dependencies
156+
npm run dev # Start dev server (localhost:4321)
157+
npm run build # Build production site
158+
npm run preview # Preview production build
159+
npm run astro check # Type check
160+
```
161+
162+
## Common Tasks
163+
164+
### Adding a New Guide
165+
1. Create new `.mdx` file in `src/content/docs/guides/`
166+
2. Add frontmatter with title and description
167+
3. Content will auto-generate in sidebar under "Guides"
168+
169+
### Adding a New Top-Level Page
170+
1. Create `.mdx` file in `src/content/docs/`
171+
2. Manually add to sidebar in `astro.config.mjs` if needed
172+
3. Follow existing patterns for structure
173+
174+
### Updating Framework Version
175+
1. Update `dynamiaToolsVersion` in `astro.config.mjs`
176+
2. Update any version references in documentation
177+
3. Update code examples if API changed
178+
179+
### Adding Images
180+
1. Place images in `src/assets/` for optimized processing
181+
2. Reference with relative paths: `../../assets/image.png`
182+
3. Alt text is required for accessibility
183+
184+
### Linking
185+
- Internal links: `/getting-started` (no file extension)
186+
- External links: Full URL with `https://`
187+
- GitHub links should point to `dynamiatools` organization
188+
189+
## Best Practices
190+
191+
1. **Keep it Simple**: Documentation should be clear and concise
192+
2. **Show, Don't Just Tell**: Include working code examples
193+
3. **Be Consistent**: Follow existing patterns and structure
194+
4. **Mobile Friendly**: Starlight handles this, but test complex layouts
195+
5. **Accessibility**: Use semantic HTML and proper alt text
196+
6. **SEO**: Write descriptive titles and descriptions
197+
7. **Version Awareness**: Specify which DynamiaTools version features require
198+
8. **Cross-reference**: Link related concepts together
199+
9. **Update Both Languages**: When adding English content, plan for Spanish translation
200+
10. **Test Locally**: Always run `npm run dev` to preview changes
201+
202+
## External Resources
203+
204+
- Starlight Docs: https://starlight.astro.build/
205+
- Astro Docs: https://docs.astro.build/
206+
- DynamiaTools Framework: https://github.com/dynamiatools/framework
207+
- DynamiaTools Main Site: https://dynamia.tools
208+
209+
## Technical Notes
210+
211+
- Astro uses **file-based routing** - file structure determines URLs
212+
- MDX allows mixing **Markdown with JSX components**
213+
- Build process includes type checking via `astro check`
214+
- Sharp library used for image optimization
215+
- Site uses **static site generation** (SSG) for best performance
216+
- CNAME file ensures proper GitHub Pages domain routing
217+
218+
## Content Review Checklist
219+
220+
Before committing documentation changes:
221+
- [ ] Frontmatter is complete and accurate
222+
- [ ] Code examples are tested and working
223+
- [ ] Links are valid and not broken
224+
- [ ] Images have alt text
225+
- [ ] Spelling and grammar checked
226+
- [ ] Consistent with existing style
227+
- [ ] Mobile-friendly layout
228+
- [ ] Accessible to screen readers
229+
- [ ] Spanish translation planned/added (if applicable)
230+
- [ ] Framework version requirements noted (if applicable)
231+

0 commit comments

Comments
 (0)