@@ -7,47 +7,19 @@ alwaysApply: true
77
88## Project Overview
99
10- This is a Jekyll -based documentation site for Nordic MathML Guidelines, featuring:
10+ This is a Markdown -based documentation site for Nordic MathML Guidelines, featuring:
1111
12- - Jekyll static site generation with GitHub Pages deployment
13- - Python scripts for LaTeX to MathML conversion
14- - Comprehensive testing infrastructure
1512- Markdown-based content with MathML examples
1613
1714## File Structure & Conventions
1815
1916### Core Files
2017
21- - `_config.yml` - Jekyll configuration
22- - `Gemfile` - Ruby dependencies for Jekyll
2318- `Nordic MathML Guidelines.md` - Source markdown content
24- - `_pages/` - Generated Jekyll pages
2519- `images/` - Documentation images and examples
2620
27- ### Scripts Directory
28-
29- - `scripts/convert-guidelines.sh` - Main conversion script (Bash)
30- - `scripts/convert-mathml.py` - LaTeX to MathML converter (Python 3)
31-
32- ### Testing
33-
34- - `tests/` - All test files
35- - `tests/test-conversion-workflow.py` - Main test suite
36- - `tests/test-conversion.sh` - Conversion testing
37- - `tests/test-local.sh` - Local testing
38-
3921## Coding Standards
4022
41- ### Python Scripts
42-
43- - Use Python 3.9+ with type hints where appropriate
44- - Follow PEP 8 style guidelines
45- - Use descriptive function and variable names
46- - Include comprehensive docstrings for functions
47- - Handle encoding explicitly (UTF-8)
48- - Use regex patterns for LaTeX to MathML conversion
49- - Implement conservative conversion to avoid breaking existing MathML
50-
5123### Bash Scripts
5224
5325- Use `set -e` for error handling
@@ -58,41 +30,13 @@ This is a Jekyll-based documentation site for Nordic MathML Guidelines, featurin
5830
5931### Markdown Content
6032
61- - Use proper Jekyll front matter
6233- Include MathML namespace: `xmlns="http://www.w3.org/1998/Math/MathML"`
6334- Preserve existing MathML examples in documentation
6435- Use code blocks for HTML and MathML examples
6536- Maintain accessibility standards for mathematical content
6637
67- ## Testing Requirements
68-
69- ### Test Coverage
70-
71- - File existence and size validation
72- - MathML conversion accuracy
73- - Namespace compliance
74- - Code block preservation
75- - LaTeX pattern conversion
76- - Error handling and edge cases
77-
78- ### Test Execution
79-
80- - Run tests before any deployment
81- - Use descriptive test output with emojis for clarity
82- - Include both unit and integration tests
83- - Test conversion workflow end-to-end
84-
8538## MathML Guidelines
8639
87- ### Conversion Rules
88-
89- - Convert simple LaTeX patterns: `$x = 5$` → x = 5
90- - Preserve existing MathML documentation examples
91- - Add MathML namespace to all `<math>` elements
92- - Handle fractions, superscripts, subscripts, and common symbols
93- - Convert display math `$$...$$` to code blocks
94- - Be conservative to avoid breaking documentation
95-
9640### Accessibility
9741
9842- Ensure all MathML includes proper namespace
@@ -102,19 +46,10 @@ This is a Jekyll-based documentation site for Nordic MathML Guidelines, featurin
10246
10347## Development Workflow
10448
105- ### Local Development
106-
107- 1. Run `bash tests/test-local.sh` for quick validation
108- 2. Use `bash scripts/convert-guidelines.sh` for conversion
109- 3. Test with `python tests/test-conversion-workflow.py`
110- 4. Verify Jekyll build with `bundle exec jekyll build`
111-
11249### GitHub Actions
11350
114- - Automated conversion and testing on push/PR
115- - Jekyll build and deployment to GitHub Pages
116- - Python 3.9 and Ruby 3.2 environment
117- - Comprehensive test suite execution
51+ - Automated Markdown Linting on pushes and PRs
52+ - Python 3.9 environment
11853
11954## Error Handling
12055
@@ -128,7 +63,6 @@ This is a Jekyll-based documentation site for Nordic MathML Guidelines, featurin
12863
12964### Bash Scripts
13065
131- - Check for required commands (python, sed)
13266- Validate file operations
13367- Clean up temporary files
13468- Provide fallback processing when possible
@@ -174,25 +108,15 @@ This is a Jekyll-based documentation site for Nordic MathML Guidelines, featurin
174108- Process content in chunks for large files
175109- Cache repeated operations where possible
176110
177- ### Jekyll Build
178-
179- - Optimize image assets
180- - Minimize build time
181- - Use appropriate Jekyll plugins
182- - Configure proper exclusions
183-
184111## Maintenance
185112
186113### Regular Tasks
187114
188- - Update dependencies (Ruby gems, Python packages)
189115- Review and update conversion patterns
190- - Validate test coverage
191116- Update documentation examples
192117
193118### Monitoring
194119
195- - Check GitHub Actions build status
196120- Monitor conversion accuracy
197121- Validate MathML output
198122- Review user feedback and issues
@@ -201,17 +125,9 @@ This is a Jekyll-based documentation site for Nordic MathML Guidelines, featurin
201125
202126### Required Tools
203127
204- - Python 3.9+ with regex support
205- - Ruby 3.2+ with Jekyll 4.3+
206128- Bash shell with standard utilities
207129- Git for version control
208130
209- ### Key Dependencies
210-
211- - Jekyll and Jekyll plugins
212- - Python standard library (re, sys, os)
213- - Standard Unix utilities (sed, grep, wc)
214-
215131## Quality Assurance
216132
217133### Code Quality
@@ -225,21 +141,17 @@ This is a Jekyll-based documentation site for Nordic MathML Guidelines, featurin
225141
226142- Validate MathML syntax
227143- Ensure accessibility compliance
228- - Test conversion accuracy
229144- Maintain documentation consistency
230145
231146## Troubleshooting
232147
233148### Common Issues
234149
235- - LaTeX patterns not converting
236150- MathML namespace missing
237151- File encoding problems
238- - Jekyll build failures
239152
240153### Debugging
241154
242155- Use verbose output in scripts
243156- Check file permissions and paths
244157- Validate input file format
245- - Test conversion patterns individually
0 commit comments