Skip to content

Conversation

owine
Copy link
Collaborator

@owine owine commented Jul 12, 2025

Summary

This PR implements comprehensive consistency and formatting improvements across the Saltbox documentation repository through a systematic two-pass review process.

First Pass Improvements

  • File Naming: Renamed FAQ files from PascalCase to kebab-case for consistency
  • YAML Frontmatter: Added frontmatter to 162+ sandbox apps for proper metadata
  • Navigation: Fixed file references in mkdocs.yml after renames
  • Code Blocks: Standardized language tags and formatting
  • Admonitions: Fixed spacing and formatting inconsistencies
  • Images: Added missing alt text for accessibility compliance

Second Pass Improvements

  • Heading Structure: Added missing H1 headings to files without proper document titles
  • Admonition Formatting: Fixed 32+ instances of \!\!\!info\!\!\! info spacing
  • Code Block Languages: Standardized bash/Bashshell, ymlyaml
  • List Formatting: Converted asterisk bullets to dash bullets for consistency
  • Link Accessibility: Replaced generic "here" links with descriptive text
  • Image Alt Text: Added accessibility descriptions to 25+ images in reference docs
  • Blank Lines: Removed excessive consecutive blank lines

Files Changed

  • 170+ files updated across documentation
  • FAQ section: Complete rename and navigation update
  • Reference docs: Comprehensive image accessibility improvements
  • Sandbox apps: Metadata standardization
  • Navigation: Updated mkdocs.yml references

Technical Improvements

  • Enhanced accessibility compliance (WCAG)
  • Improved SEO through proper heading hierarchy
  • Better syntax highlighting with standardized code block languages
  • Consistent markdown formatting throughout
  • Cross-platform compatibility fixes

Test plan

  • Verify all internal links work after file renames
  • Confirm navigation structure remains intact
  • Test that renamed files are accessible via new URLs
  • Validate markdown syntax across changed files
  • Check image accessibility improvements

@owine owine requested a review from chazlarson July 12, 2025 20:48
Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:c626ee65856ed1f634ac5b4d9338afa76c98e412
Status: ❌  Build failed!
Preview URL:
Branch Preview URL:
Build logs:View build logs

Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:6a74d435bc56d4b5803a6390b95b93200c495e3a
Status: ❌  Build failed!
Preview URL:
Branch Preview URL:
Build logs:View build logs

Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:6e3f6041a81f2bbdadf60c9ccb6ecb1592581091
Status: ❌  Build failed!
Preview URL:
Branch Preview URL:
Build logs:View build logs

Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:c2a2ade37b7441a1e52652facf4e05dfc980cfcb
Status: ✅  Deploy successful!
Preview URL:https://b5d80701.docs-acq.pages.dev
Branch Preview URL:https://pr-349.docs-acq.pages.dev
Build logs:View build logs

Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:5c9cd5f67fba128cbb032eab7b67872efda7ba34
Status: ❌  Build failed!
Preview URL:
Branch Preview URL:
Build logs:View build logs

Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:ca6abb77955809cc9319744b14a464847507b1eb
Status: ✅  Deploy successful!
Preview URL:https://ad27d98b.docs-acq.pages.dev
Branch Preview URL:https://pr-349.docs-acq.pages.dev
Build logs:View build logs

owine added 14 commits August 15, 2025 10:23
- FAQ: Backup and Restore.md → backup-and-restore.md
- FAQ: Cloud Storage.md → cloud-storage.md
- Saltbox: accessing_apps.md → accessing-apps.md
- Saltbox: install_types.md → install-types.md
- Apps: hetzner_nfs.md → hetzner-nfs.md
- Update mkdocs.yml navigation references
- Add standardized frontmatter with hide/tags metadata
- Include semantic tags for app categorization
- 162+ apps now have consistent frontmatter structure
- Improves SEO and navigation organization
- Add descriptive alt text for folder selection images
- Improves accessibility compliance
- Replaces empty space alt text with meaningful descriptions
- Update all references to renamed files
- Fix broken links to accessing-apps.md, install-types.md, hetzner-nfs.md
- Ensures documentation builds without warnings
- Properly rename ruTorrent.md to rutorrent.md
- Resolves navigation mismatch in mkdocs.yml
- Fixes case-sensitive filesystem compatibility
Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:7fb3a7e9310af0baca09cbc630cd6e8230a7b360
Status: ✅  Deploy successful!
Preview URL:https://3e87675e.docs-acq.pages.dev
Branch Preview URL:https://pr-349.docs-acq.pages.dev
Build logs:View build logs

- Standardize Saltbox, Cloudflare, Google Drive capitalization
- Fix grammar issues in your-own-containers page
- Improve writing clarity and punctuation
- Correct possessive forms and compound sentences
@owine owine force-pushed the docs/consistency-improvements branch from 7fb3a7e to 85291a7 Compare August 15, 2025 15:32
Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:85291a7bc76e969471e350cee3831f2e5abd1e70
Status: ❌  Build failed!
Preview URL:
Branch Preview URL:
Build logs:View build logs

- Update link fragment to match actual heading ID
- Fixes warning about missing anchor #docker-compose
Copy link
Contributor

Deploying with ⚡ Cloudflare Pages

Latest commit:11270dbc43e78b268e8d53a23b91460562516a51
Status: ✅  Deploy successful!
Preview URL:https://4ea0a254.docs-acq.pages.dev
Branch Preview URL:https://pr-349.docs-acq.pages.dev
Build logs:View build logs

@owine owine merged commit de59588 into main Aug 15, 2025
2 checks passed
@owine owine deleted the docs/consistency-improvements branch August 15, 2025 15:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant