|
| 1 | +# XML to Markdown Conversion Notes |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The `entries/` directory contained 39 XML files that defined the API documentation for individual validation methods, selectors, and validator functions. These have been converted to Markdown format and moved to the `_entries/` directory for use with Jekyll. |
| 6 | + |
| 7 | +## Conversion Process |
| 8 | + |
| 9 | +1. **Script**: `convert_entries.py` - Python script that parses XML and generates Markdown |
| 10 | +2. **Source**: `entries/*.xml` (39 files) |
| 11 | +3. **Output**: `_entries/*.md` (39 files) |
| 12 | + |
| 13 | +## Conversion Details |
| 14 | + |
| 15 | +Each XML file was transformed as follows: |
| 16 | + |
| 17 | +### Front Matter |
| 18 | +- `title`: From `<title>` element |
| 19 | +- `entry_name`: From `name` attribute of root `<entry>` |
| 20 | +- `entry_type`: From `type` attribute (method, selector, validator) |
| 21 | +- `return_type`: From `return` attribute (if present) |
| 22 | +- `category`: From `<category slug="">` element |
| 23 | +- `layout`: Set to "default" |
| 24 | + |
| 25 | +### Content Structure |
| 26 | +- **Title**: H1 heading from `<title>` |
| 27 | +- **Sample**: For selectors, the selector syntax from `<sample>` |
| 28 | +- **Description**: From `<desc>` element |
| 29 | +- **Long Description**: From `<longdesc>` element (with HTML preserved as markdown) |
| 30 | +- **Usage/Signatures**: From `<signature>` elements with nested arguments and properties |
| 31 | +- **Examples**: From `<example>` elements with JavaScript and HTML code blocks |
| 32 | + |
| 33 | +## Jekyll Configuration |
| 34 | + |
| 35 | +The `_config.yml` has been configured to: |
| 36 | +- Define `entries` as a collection |
| 37 | +- Output entries with permalink pattern `/:name/` |
| 38 | +- Apply the default layout to all entries |
| 39 | +- Exclude the old `entries/` directory and conversion script from builds |
| 40 | + |
| 41 | +## URL Mapping |
| 42 | + |
| 43 | +With the permalink configuration, entries are accessible at: |
| 44 | +- `/validate/` → `_entries/validate.md` |
| 45 | +- `/required-method/` → `_entries/required-method.md` |
| 46 | +- `/blank-selector/` → `_entries/blank-selector.md` |
| 47 | +- etc. |
| 48 | + |
| 49 | +This matches the link structure already present in `documentation.md`. |
| 50 | + |
| 51 | +## Original XML Files |
| 52 | + |
| 53 | +The original XML files in the `entries/` directory are: |
| 54 | +- Excluded from Jekyll processing (in `_config.yml`) |
| 55 | +- Kept for reference |
| 56 | +- Can be removed once the conversion is verified in production |
| 57 | + |
| 58 | +## Testing |
| 59 | + |
| 60 | +To verify the conversion: |
| 61 | +1. Check that all 39 entries are present in `_entries/` |
| 62 | +2. Verify front matter is correct for each file |
| 63 | +3. Ensure links in `documentation.md` resolve correctly |
| 64 | +4. Test the GitHub Pages deployment |
| 65 | + |
| 66 | +## Files Created/Modified |
| 67 | + |
| 68 | +**Created:** |
| 69 | +- `_entries/*.md` (39 files) |
| 70 | +- `convert_entries.py` |
| 71 | +- This file (`CONVERSION_NOTES.md`) |
| 72 | + |
| 73 | +**Modified:** |
| 74 | +- `_config.yml` - Updated collections, permalink, and excludes |
| 75 | + |
| 76 | +**Preserved (for reference):** |
| 77 | +- `entries/*.xml` (39 files) - Original XML sources |
0 commit comments