v4 Documentation Freshening

[mattstein]

Description

This PR thoroughly edits and reorganizes the docs to read like a more structured product manual that’s stylistically consistent and (hopefully) easier to navigate.

• Adds meaningful alt text to all screenshot images
• Removes redundant “brought to you by” language from every page
• Reorganizes the navigation into distinct sections and sub-pages
• Consolidates redundant information and varies language to be less repetitive
• Gets rid of curious const EVENT_* lines from the events page that don’t seem to have a clear purpose
• Randomly whittles down language for brevity and clarity
• Opens every page with a summary of its purpose and contents
• Starts following more Craft CMS conventions for capitalization and style
• Cross-links some mentioned sections for more fluid navigation
• Fixes inconsistent formatting and corrects proper noun offenses
  • Code block whitespace
  • Event handler examples
  • Code examples readable without horizontal scrolling
  • OpenGraph → Open Graph
• Fixes broken links as a result of the reorganization

Not Done

Because time. But not the worst ideas.

• Update all screenshots, and re-add seomatic-global-security.png—which did not, in fact, depict the global security settings.
• Independently fact check everything and look for any missed features or common misunderstandings.
• Document common patterns and use cases as a guide and reinforcement of reference material. (Could clash with existing blog posts!)
• Write a new section of verifying SEO health once a site seems like it’s in good shape.
• Visualize the meta cascade for emphasis, since Content SEO is a major plugin feature and being aware of it will benefit anyone’s experience.
• Re-read and apply max scrutiny for flow and clarity.
• Find every cross-linking opportunity and add more links.
• Work through every textlint warning, not just the errors. Eliminate weasel words.

What Now?

It’s ... a lot. I would recommend the following high-level tour:

• Examine the updated landing page, particularly the Key Features summary, and revamped structure for high-level feelings
• Make sure code blocks feel good—the most potentially-offensive changes being my attempt to narrow the empty coalescing page examples
• Skim the page introductions, some of them new, to look for anything objectionable

If this is merge-worthy, I can follow up and apply these changes to the v3 and v5 docs. (As part of the PR or a separate one.)

Bonus

Here’s a slick way to check external and internal links (with fragments!) if you’re an animal that runs global Node.js modules right on your machine:

npm install -g markdown-link-check
cd /path/to/craft-seomatic/docs/docs/
find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check

(Inspired by DDEV’s setup.)