Skip to content

Commit 07b716d

Browse files
FridayCandourFridayCandour
committed
docs: add comprehensive documentation and build manifest generation
- Add CHANGELOG.md with version history and migration guides - Add CONTRIBUTING.md with development guidelines and workflow - Add ROADMAP.md with strategic development plan for versions 1.1-2.0 - Generate docmach-manifest.json containing page metadata and tag information - Add new documentation pages: advanced-features.md, api-reference.md, examples.md - Update existing documentation: configuration.md, introduction.md, quickstart.md - Update README.md with enhanced examples and CLI documentation - Update compiler.ts to extract tag metadata before processing - Update parser.ts to collect page metadata during compilation - Regenerate all HTML output files with updated content - Update HTML templates and fragments for consistency - Update package.json with latest dependencies - Add .kiro to .gitignore - Remove old package tarball (docmach-1.0.18.tgz) - Add sitemap.xml for improved SEO
1 parent 2849265 commit 07b716d

36 files changed

Lines changed: 7724 additions & 1817 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,4 @@ websites-templates
1818
dist
1919
in.ts
2020
manifest.json
21+
.kiro

‎CHANGELOG.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Changelog
2+
3+
All notable changes to Docmach will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.20] - 2025-12-07
9+
10+
### Added
11+
12+
- **Build Manifest Generation** - Automatically generates `docmach-manifest.json` containing all pages, links, and docmach tag metadata
13+
- Manifest includes source paths, output paths, URL links, and complete tag information
14+
- Metadata extraction for all docmach tags (fragments, functions, wrappers)
15+
- Enhanced documentation with advanced features guide
16+
- API reference documentation
17+
- Comprehensive roadmap for future development
18+
- Contributing guidelines
19+
20+
### Changed
21+
22+
- Improved compiler to extract tag metadata before processing
23+
- Parser now collects page metadata during compilation
24+
- Manifest only generated during full builds (not incremental updates)
25+
26+
### Documentation
27+
28+
- Added `docs/docs/advanced-features.md` - Advanced usage patterns
29+
- Added `docs/docs/api-reference.md` - Complete API documentation
30+
- Added `ROADMAP.md` - Strategic development plan
31+
- Added `CONTRIBUTING.md` - Contribution guidelines
32+
- Enhanced README with better examples and CLI documentation
33+
34+
## [1.0.19] - Previous Release
35+
36+
### Features
37+
38+
- Markdown compilation with syntax highlighting (highlight.js)
39+
- Custom templating system with `<docmach>` tags
40+
- Fragment templates with variable substitution
41+
- Function templates for dynamic content
42+
- Wrapper templates for layout composition
43+
- Tailwind CSS integration
44+
- Live development server with WebSocket hot reload
45+
- File watching with incremental builds
46+
- Template caching with LRU cache
47+
- Asset copying and management
48+
- CLI commands: `docmach`, `docmach build`, `docmach print`
49+
50+
### Core Capabilities
51+
52+
- Markdown-it parser with HTML support
53+
- Chokidar file watcher
54+
- WebSocket server for live reload
55+
- Throttled rebuilds (250ms)
56+
- Template dependency tracking
57+
- Incremental asset copying
58+
- Auto port selection (starting from 4000)
59+
60+
## Upcoming Features
61+
62+
See [ROADMAP.md](ROADMAP.md) for planned features:
63+
64+
### Version 1.1 (Q1 2026)
65+
66+
- Plugin system with hooks
67+
- Interactive CLI with project scaffolding
68+
- Multiple config format support
69+
- Enhanced error messages
70+
71+
### Version 1.2 (Q2 2026)
72+
73+
- Frontmatter support (YAML/TOML)
74+
- Collections and taxonomies
75+
- Pagination
76+
- Content helpers (TOC, reading time, related posts)
77+
78+
### Version 1.3 (Q3 2026)
79+
80+
- Parallel processing
81+
- Image optimization
82+
- Asset bundling
83+
- CDN integration
84+
85+
### Version 2.0 (Q4 2026)
86+
87+
- Internationalization (i18n)
88+
- Component system
89+
- External data sources
90+
- Advanced templating features
91+
92+
## Migration Guides
93+
94+
### Upgrading to 1.0.20
95+
96+
No breaking changes. The manifest feature is automatically enabled during builds.
97+
98+
**New files generated:**
99+
100+
- `{build-directory}/docmach-manifest.json`
101+
102+
**To use the manifest:**
103+
104+
```js
105+
import manifest from "./docmach/docmach-manifest.json";
106+
107+
// Access page metadata
108+
manifest.pages.forEach((page) => {
109+
console.log(page.link, page.docmachTags);
110+
});
111+
```
112+
113+
## Support
114+
115+
- **Issues:** [GitHub Issues](https://github.com/CodeDynasty-dev/Docmach/issues)
116+
- **Discussions:** [GitHub Discussions](https://github.com/CodeDynasty-dev/Docmach/discussions)
117+
- **Documentation:** [docs/](docs/)
118+
119+
---
120+
121+
[1.0.20]: https://github.com/CodeDynasty-dev/Docmach/releases/tag/v1.0.20
122+
[1.0.19]: https://github.com/CodeDynasty-dev/Docmach/releases/tag/v1.0.19

‎CONTRIBUTING.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
# Contributing to Docmach
2+
3+
Thank you for your interest in contributing to Docmach! This guide will help you get started.
4+
5+
## Code of Conduct
6+
7+
Be respectful, inclusive, and constructive. We're building a welcoming community.
8+
9+
## Getting Started
10+
11+
### Prerequisites
12+
13+
- Node.js >= 14.0.0 or Bun >= 0.1.0
14+
- Git
15+
- TypeScript knowledge
16+
17+
### Setup Development Environment
18+
19+
```bash
20+
# Clone the repository
21+
git clone https://github.com/CodeDynasty-dev/Docmach.git
22+
cd Docmach
23+
24+
# Install dependencies
25+
npm install
26+
27+
# Watch TypeScript files
28+
npm run watch
29+
30+
# In another terminal, run dev server
31+
npm run dev
32+
```
33+
34+
## Project Structure
35+
36+
```
37+
src/
38+
├── index.ts # CLI entry point, dev server, file watcher
39+
├── parser.ts # File discovery, build pipeline
40+
├── compiler.ts # Markdown compilation, tag processing
41+
└── print.ts # Build output utilities
42+
43+
docs/ # Documentation source (Markdown)
44+
fragments/ # Reusable HTML templates and JS functions
45+
assets/ # Static assets
46+
docmach/ # Generated output (gitignored)
47+
dist/ # Compiled TypeScript (gitignored)
48+
```
49+
50+
## Development Workflow
51+
52+
### Making Changes
53+
54+
1. **Create a branch**
55+
56+
```bash
57+
git checkout -b feature/your-feature-name
58+
```
59+
60+
2. **Make your changes**
61+
62+
- Write clean, readable code
63+
- Follow existing code style
64+
- Add comments for complex logic
65+
66+
3. **Test your changes**
67+
68+
```bash
69+
# Compile TypeScript
70+
npm run compile
71+
72+
# Test the CLI
73+
npx docmach build
74+
75+
# Test dev server
76+
npx docmach
77+
```
78+
79+
4. **Check for errors**
80+
81+
```bash
82+
# TypeScript compilation
83+
npm run watch
84+
85+
# Look for type errors
86+
```
87+
88+
### Code Style
89+
90+
- **TypeScript:** Use strict mode, explicit types where helpful
91+
- **Naming:** camelCase for variables/functions, PascalCase for classes
92+
- **Imports:** Group by native, packages, then local files
93+
- **Comments:** Explain "why", not "what"
94+
95+
### Commit Messages
96+
97+
Use clear, descriptive commit messages:
98+
99+
```
100+
feat: add plugin system for extensibility
101+
fix: resolve template caching issue
102+
docs: update API reference with examples
103+
refactor: simplify parameter parsing logic
104+
perf: optimize file watching with throttling
105+
```
106+
107+
**Format:** `type: description`
108+
109+
**Types:**
110+
111+
- `feat`: New feature
112+
- `fix`: Bug fix
113+
- `docs`: Documentation changes
114+
- `refactor`: Code refactoring
115+
- `perf`: Performance improvement
116+
- `test`: Adding tests
117+
- `chore`: Maintenance tasks
118+
119+
## Areas to Contribute
120+
121+
### High Priority
122+
123+
1. **Plugin System** - Enable third-party extensions
124+
2. **Frontmatter Support** - Parse YAML/TOML metadata
125+
3. **Performance** - Parallel processing, better caching
126+
4. **Testing** - Unit and integration tests
127+
5. **Documentation** - More examples and guides
128+
129+
### Good First Issues
130+
131+
Look for issues labeled `good-first-issue`:
132+
133+
- Documentation improvements
134+
- Example sites and templates
135+
- Bug fixes with clear reproduction steps
136+
- Small feature additions
137+
138+
### Feature Requests
139+
140+
Before implementing a new feature:
141+
142+
1. Check if an issue exists
143+
2. Create a discussion/issue to gather feedback
144+
3. Wait for maintainer approval
145+
4. Implement with tests and documentation
146+
147+
## Testing
148+
149+
### Manual Testing
150+
151+
```bash
152+
# Build the project
153+
npm run compile
154+
155+
# Test on example docs
156+
npx docmach build
157+
158+
# Check generated output
159+
ls -la docmach/
160+
161+
# Verify manifest
162+
cat docmach/docmach-manifest.json
163+
```
164+
165+
### Test Checklist
166+
167+
- [ ] TypeScript compiles without errors
168+
- [ ] Dev server starts and serves files
169+
- [ ] Live reload works
170+
- [ ] Build command generates correct output
171+
- [ ] Manifest includes all pages
172+
- [ ] Assets are copied correctly
173+
- [ ] Tailwind CSS compiles
174+
- [ ] All docmach tags work (fragment, function, wrapper)
175+
176+
## Documentation
177+
178+
### Writing Documentation
179+
180+
- Use clear, concise language
181+
- Include code examples
182+
- Add use cases and best practices
183+
- Test all code snippets
184+
185+
### Documentation Structure
186+
187+
```
188+
docs/docs/
189+
├── introduction.md # Overview and getting started
190+
├── quickstart.md # Quick setup guide
191+
├── configuration.md # Config options
192+
├── advanced-features.md # Advanced usage
193+
└── api-reference.md # Complete API docs
194+
```
195+
196+
## Pull Request Process
197+
198+
1. **Update documentation** if you changed functionality
199+
2. **Add examples** for new features
200+
3. **Test thoroughly** on different scenarios
201+
4. **Update CHANGELOG.md** with your changes
202+
5. **Submit PR** with clear description
203+
204+
### PR Template
205+
206+
```markdown
207+
## Description
208+
209+
Brief description of changes
210+
211+
## Type of Change
212+
213+
- [ ] Bug fix
214+
- [ ] New feature
215+
- [ ] Breaking change
216+
- [ ] Documentation update
217+
218+
## Testing
219+
220+
How did you test this?
221+
222+
## Checklist
223+
224+
- [ ] Code compiles without errors
225+
- [ ] Documentation updated
226+
- [ ] Examples added
227+
- [ ] Tested manually
228+
```
229+
230+
## Release Process
231+
232+
Maintainers handle releases:
233+
234+
1. Update version in `package.json`
235+
2. Update `CHANGELOG.md`
236+
3. Create git tag
237+
4. Publish to npm
238+
5. Create GitHub release
239+
240+
## Getting Help
241+
242+
- **GitHub Issues:** Bug reports and feature requests
243+
- **GitHub Discussions:** Questions and ideas
244+
- **Discord:** Real-time chat (coming soon)
245+
246+
## Recognition
247+
248+
Contributors are recognized in:
249+
250+
- README.md contributors section
251+
- Release notes
252+
- GitHub contributors page
253+
254+
## License
255+
256+
By contributing, you agree that your contributions will be licensed under the Apache License.
257+
258+
---
259+
260+
Thank you for contributing to Docmach! 🚀

0 commit comments

Comments
 (0)