Markzen SEO — Documentation

Version 1.0 · [markzentech.com](https://markzentech.com) · [WordPress.org Plugin Page](https://wordpress.org/plugins/markzen-seo/)

> Fast, clean SEO for WordPress. No bloat. No noise.

---

Table of Contents

1. [What is Markzen SEO?](#1-what-is-markzen-seo) 2. [Installation & Setup](#2-installation--setup) 3. [The Dashboard](#3-the-dashboard) 4. [Site Health](#4-site-health) 5. [SEO Meta Box — Per-Post & Per-Page Settings](#5-seo-meta-box--per-post--page-settings) 6. [Posts & Pages](#6-posts--pages) 7. [Focus Keyphrases](#7-focus-keyphrases) 8. [Global Settings](#8-global-settings) 9. [XML Sitemap](#9-xml-sitemap) 10. [robots.txt Editor](#10-robotstxt-editor) 11. [Broken Link Checker](#11-broken-link-checker) 12. [Image Alt Tag Audit](#12-image-alt-tag-audit) 13. [Third-Party Script Detector](#13-third-party-script-detector) 14. [Lighthouse / PageSpeed Audit](#14-lighthouse--pagespeed-audit) 15. [Exporting Data to CSV](#15-exporting-data-to-csv) 16. [For Website Managers — Weekly SEO Workflow](#16-for-website-managers--weekly-seo-workflow) 17. [For Marketing Teams — Decision Making with Markzen SEO](#17-for-marketing-teams--decision-making-with-markzen-seo) 18. [What Markzen SEO Outputs to Your Site](#18-what-markzen-seo-outputs-to-your-site) 19. [Upcoming Features](#19-upcoming-features) 20. [FAQ](#20-faq)

---

1. What is Markzen SEO?

Markzen SEO is a WordPress plugin that handles the technical and content SEO work that actually moves rankings — without burying you in settings you'll never touch or a "score" that always finds something wrong.

It is built for two types of users working on the same site:

Website managers and developers who need to know the site is technically correct — sitemaps submitted, meta tags in place, no broken links, schema data output properly, page speed acceptable.

Marketing and content teams who need to optimise individual posts and pages for specific search terms, understand how content is performing, and make prioritised decisions about what to fix next.

Markzen SEO adds zero JavaScript and zero CSS to your public-facing pages. Every audit runs in the background. The admin interface was designed to be understood in under thirty seconds.

---

2. Installation & Setup

Installing the plugin

1. In your WordPress admin, go to Plugins → Add New Plugin 2. Search for Markzen SEO 3. Click Install Now, then Activate

Or download the zip from [wordpress.org/plugins/markzen-seo](https://wordpress.org/plugins/markzen-seo/) and upload it via Plugins → Add New Plugin → Upload Plugin.

First-time setup (takes about 5 minutes)

After activating, a new Markzen SEO section appears in your WordPress sidebar.

Step 1 — Go to Markzen SEO → Settings → General

Set your: - Title separator — the character between post title and site name in browser tabs (e.g. `Post Title | Site Name`) - Default title template — what appears when no custom SEO title is set on a post - Homepage SEO title and description — these are high-priority; set them now

Step 2 — Settings → Social

• Add your Facebook page URL, Twitter/X handle, and LinkedIn URL
• Upload a default social image — this is used when someone shares a page that has no featured image

Step 3 — Settings → Schema

• Enter your organisation name and logo — these power the structured data output across your entire site

Step 4 — Settings → Sitemap

• Confirm the sitemap is enabled (it is by default)
• Choose which post types to include
• Enable Ping Google and Ping Bing if you want search engines notified when you publish

Step 5 — Run your first scans

From the Dashboard, click: - Start broken link scan — finds broken links across all your content - Scan images for missing alt text — audits image accessibility

Both run in the background. Results appear in their respective tool pages.

---

3. The Dashboard

Markzen SEO → Dashboard

The dashboard is your weekly SEO health check. It shows you what needs attention across your site at a glance, without requiring you to dig through individual posts.

Summary cards

Four cards at the top surface the most actionable numbers:

| Card | What it means | Action | |---|---|---| | Missing meta description | Posts and pages with no meta description set | Click to go to Posts & Pages filtered to those items | | Broken links | Links across your site returning 404, 500, or timing out | Click to go to the Broken Links tool | | Images missing alt text | Images without descriptive alt attributes | Click to go to Image Audit | | Missing focus keyphrase | Posts with no target keyword assigned | Click to go to Posts & Pages filtered to those items |

Needs attention

A list of your six most recently modified posts and pages that have a known SEO issue — no meta description, no keyphrase, or a broken link. Each item links directly to the WordPress post editor so you can fix it immediately.

Quick actions

Buttons to trigger background scans and maintenance tasks without navigating away from the dashboard.

Site health at a glance

Three compact cards showing: - Sitemap — total URLs indexed, with a direct link to view your sitemap - Lighthouse SEO — your site's average SEO score across audited pages - Robots.txt — whether your robots.txt is active, and a warning if a physical file is overriding the plugin's settings

---

4. Site Health

Markzen SEO → Site Health

A single-page summary of your site's SEO configuration across every Markzen tool. Each item is clickable and links directly to the relevant tool page.

| Check | Pass condition | |---|---| | XML sitemap | Enabled and generating correctly | | robots.txt | No physical file conflict detected | | Broken links | Zero broken links found in last scan | | Image alt text | Zero images missing alt text in last scan | | Lighthouse SEO score | Average SEO score ≥ 90 across audited pages | | Meta description coverage | ≥ 90% of published content has a meta description |

Use Site Health as your monthly report card — if everything is green, your site's technical SEO foundation is solid.

---

5. SEO Meta Box — Per-Post & Per-Page Settings

This is where you set the SEO details for each individual piece of content. It appears below the editor on every post, page, and custom post type.

SEO tab

Focus keyphrase The main search term this piece of content is targeting. Setting this unlocks the full SEO analysis checklist below. Keep it specific — "wordpress seo plugin for small business" is better than "seo".

SEO title What appears in browser tabs and Google search results. The character counter turns: - Green at 0–60 characters (ideal range) - Amber at 61–70 (slightly long, may be truncated) - Red above 70 (will be cut off in search results)

Leave it empty to use the global title template from Settings. Use tokens like `{post_title}`, `{site_name}`, or `{separator}` to build dynamic titles.

Meta description The snippet that appears under your title in search results. The counter turns: - Green at 120–160 characters (ideal range) - Amber at 161–175 (slightly long) - Red above 175 (will be truncated)

Search preview A live simulation of how your result will look in Google, updating as you type. Toggle between Desktop and Mobile to see both layouts.

SEO analysis checklist

Runs automatically when you set a focus keyphrase. Each item shows pass (✅), warning (⚠️), or fail (❌):

| Check | What's being measured | |---|---| | Focus keyphrase is set | Has a keyphrase been entered | | Keyphrase in SEO title | Does the title contain the keyphrase | | Keyphrase in meta description | Does the description include the keyphrase | | Keyphrase in URL slug | Does the permalink contain the keyphrase | | Keyphrase in first paragraph | Is the keyphrase mentioned early in the content | | Keyphrase density | Is the keyphrase used naturally (0.5–2.5% is the target range) | | SEO title length | Is the title within the 30–60 character range | | Meta description length | Is the description within the 120–160 character range | | Content length | At least 300 words for posts, 100 for pages | | H1 heading | Exactly one H1 exists in the content | | Heading structure | Headings follow a logical order (H2 → H3, no skipping) | | Images present | At least one image in the content | | Image alt text | All images have descriptive alt attributes | | Internal links | At least one link to another page on your site | | Outbound links | At least one link to an external source |

Click any failed item to expand a plain-language explanation of how to fix it.

Important note on the checklist: These are guidelines, not rigid rules. A short landing page may intentionally have no outbound links. A homepage may not need a focus keyphrase. Use your judgment — the checklist surfaces what's worth checking, not what must always be true.

Social tab

Override the default social sharing image, title, and description specifically for Facebook/LinkedIn (Open Graph) and Twitter/X. Leave these empty and the SEO title and description are used automatically.

Recommended image size: 1200 × 630px. Minimum: 600 × 315px.

Advanced tab

Canonical URL — Leave empty for standard pages. Set this if the same content appears at multiple URLs (e.g. a product page accessible under multiple category paths) and you want to tell search engines which URL is the "official" one.

Noindex — Tick this to prevent search engines from indexing this specific page. Use for thin content, duplicate pages, thank-you pages, and content you don't want in search results. A yellow warning banner appears when noindex is enabled so it's never accidentally set and forgotten.

Nofollow — Prevents search engines from following links on this page. Rarely needed.

Schema type — Markzen auto-detects the correct schema type (BlogPosting for posts, WebPage for pages). Override only if you know the content needs a specific type like FAQPage or Article.

---

6. Posts & Pages

Markzen SEO → Posts & Pages

A full SEO status table across all your published content — the command centre for a content audit.

Filtering

Type tabs — Switch between All, Posts, and Pages to focus on one content type.

Search — Filter by title or URL slug. Useful when auditing a specific section of a large site.

SEO filters — Deep links from the Dashboard cards land here with a filter pre-applied, e.g. "show only posts missing a meta description."

Reading the table

Each row shows: - Post title and URL slug - Content type (Post / Page) - SEO title status (Set ✅ or Using global template) - Meta description status (Set ✅ or Missing ❌) - Focus keyphrase (shown if set, "Not set" warning if missing)

Click Edit to go directly to that post's WordPress editor and set what's missing.

Pagination

20 results per page. If you have 200 posts and want to work through them systematically, use the page number links at the bottom.

Exporting

Click Export CSV to download the current filtered view as a spreadsheet. Export the "missing meta description" filter to get a prioritised work list for your content team.

---

7. Focus Keyphrases

Markzen SEO → Keyphrases

A site-wide view of every focus keyphrase being used, and which posts are targeting them.

Duplicate detection

If two or more posts are targeting the same keyphrase, they appear grouped with a Duplicate badge. This is called keyword cannibalization — your own pages are competing against each other for the same search term, which weakens both.

What to do when you see a duplicate: - Decide which page is the primary target for that term - Redirect or merge the weaker page into the stronger one, OR - Differentiate the keyphrases — target the general term on one page and a more specific long-tail variation on the other

Unique badge means the keyphrase is only used on one page — no cannibalization.

Export this view to CSV for a keyphrase audit spreadsheet.

---

8. Global Settings

Markzen SEO → Settings

Settings are organised into five tabs.

General

• Title separator — character between post title and site name (dash, pipe, dot, colon, middot)
• Default title template — used when no custom SEO title is set. Use `{post_title} | {site_name}` or similar token combinations
• Default description template — fallback when no custom description is set
• Homepage SEO title and description — set these specifically; the homepage is typically your most important page
• Noindex settings — choose which page types to hide from search engines by default (search results pages, tag archives, date archives, author archives)

Social

• Social profile URLs for Open Graph `sameAs` schema
• Default OG image for pages without a featured image
• Twitter card type (Summary or Summary with large image)

Sitemap

• Enable/disable the XML sitemap
• Choose which post types and taxonomies are included
• Enable Google and Bing pings when content is published
• View and copy your sitemap URL

Schema

• Organisation name, URL, and logo (used in structured data across the entire site)
• Social profiles for `sameAs` linking
• Local business schema toggle (for brick-and-mortar businesses)

Advanced

• WordPress head cleanup — remove the generator tag, RSD link, and other unnecessary `` elements
• PageSpeed Insights API key — optional, but adds higher rate limits for Lighthouse audits

All settings save instantly via AJAX — no page reload required.

---

9. XML Sitemap

Markzen SEO → Sitemap

Your sitemap tells search engines about every piece of content on your site and when it was last updated.

Your sitemap URL

``` https://yoursite.com/sitemap.xml ```

This is a sitemap index — a master file linking to separate child sitemaps organised by content type (posts, pages, categories, custom post types). This structure scales to sites with thousands of pages without any single file becoming unwieldy.

What's included

Configure in Settings → Sitemap: - Posts and pages (on by default) - Custom post types (you choose which) - Categories and tags

What's automatically excluded

• Noindexed pages (set per-post in the Advanced tab of the SEO meta box)
• Password-protected content
• Posts with a canonical URL pointing to a different domain
• Drafts and unpublished content

Search engine pings

When you publish or update content, Markzen SEO can automatically notify Google and Bing. Enable this in Settings → Sitemap. Pings are rate-limited to once per minute to avoid triggering spam detection.

Regenerating the sitemap

The sitemap updates automatically when content is published, updated, or deleted. If you need to force a refresh (e.g. after changing which post types are included), click Regenerate sitemap on the Sitemap page.

Submitting to Google Search Console

After Phase 2's Google Search Console integration is available, you'll be able to submit your sitemap directly from within Markzen SEO. For now, submit it manually: 1. Go to [search.google.com/search-console](https://search.google.com/search-console) 2. Select your property 3. Go to Sitemaps → Add a new sitemap 4. Enter your sitemap URL and click Submit

---

10. robots.txt Editor

Markzen SEO → Robots.txt

robots.txt tells search engine crawlers which parts of your site they can and cannot access. Most sites need only minor customisation of the WordPress default.

Presets

Three one-click presets:

Default WordPress — allows all crawlers, blocks only `/wp-admin/`, includes your sitemap URL. Correct for most sites.

Allow AI crawlers — same as default, but explicitly permits AI research crawlers (GPTBot, ClaudeBot, Google-Extended, PerplexityBot). Use this if you want your content to be indexable by AI tools.

Block all crawlers — `Disallow: /`. Use only for sites under maintenance, staging environments, or private intranets that have somehow ended up publicly accessible.

Editor

The textarea editor allows direct editing of your robots.txt content. Markzen SEO validates the syntax before saving and will show specific error messages if something is malformed.

Physical file conflict warning

If a `robots.txt` file exists physically on your server (in the same directory as `wp-config.php`), a prominent red warning appears. This physical file takes priority over WordPress's virtual robots.txt — meaning Markzen SEO's settings have no effect until it's removed. The warning includes a preview of the conflicting file's contents and a Re-check button for after you've resolved it.

Important

robots.txt controls crawl access, not indexing. A page blocked in robots.txt can still appear in search results if another site links to it — it just won't be crawled. To prevent indexing, use the Noindex setting in the SEO meta box Advanced tab instead.

---

11. Broken Link Checker

Markzen SEO → Broken Links

Broken links damage user experience and signal poor site maintenance to search engines. Markzen SEO scans all your published content for broken internal and external links automatically.

Running a scan

Click Start scan. The scanner: - Works through all published posts and pages in batches of 10 - Checks each link using an HTTP request (HEAD method, falling back to GET) - Deduplicates — the same URL appearing across 20 posts is checked once - Runs in the background — you can navigate away and return later

Understanding the results

| Status badge | Meaning | Action needed | |---|---|---| | 🔴 404 / 500 / Timeout | Broken — the link leads nowhere or the server is down | Update or remove the link | | 🟡 301 / 302 | Redirect — the link works but forwards to another URL | Update to the final destination URL directly | | 🟢 200 | Working — no action needed | None |

Filtering

Use the tabs to view All, Broken, or Redirects specifically. Export the broken links view to CSV for a prioritised fix list.

Actions per link

• Recheck — re-tests that specific URL right now (useful after you've fixed something)
• Ignore — removes it from the default view without deleting the record. Use this for false positives (e.g. links to internal staging URLs, or sites that correctly return non-200 responses for authenticated content)

Scheduled scanning

Markzen SEO runs an automatic full scan weekly in the background. The dashboard shows when the last scan completed.

Reading the results strategically

Prioritise internal broken links first — a broken link from one of your own pages to another wastes crawl budget and breaks the user journey on your site. Broken external links second — these damage credibility with readers. Redirect chains are lower priority but worth fixing progressively — each redirect hop adds latency.

---

12. Image Alt Tag Audit

Markzen SEO → Image Audit

Alt text serves two purposes: it describes images to screen readers (accessibility) and gives search engines context about what an image contains (SEO). Missing alt text is one of the most common and easily fixed SEO issues on established sites.

Running a scan

Click Start scan. The auditor scans all published posts and pages for `` tags, then flags any image where the `alt` attribute is absent or empty.

Reading the results

Results are grouped by post. Each flagged image shows: - A small thumbnail so you can identify it visually - A text snippet showing the surrounding content so you know where in the post it appears - An Edit in Media Library link if the image is in your WordPress Media Library

What to write for alt text

Good alt text is specific and descriptive: - ❌ `image.jpg` — useless - ❌ `photo` — useless - ❌ `banner image for post about SEO` — too generic - ✅ `Screenshot of the Markzen SEO dashboard showing four stat cards` — descriptive and specific - ✅ `Bar chart comparing organic traffic before and after technical SEO fixes` — describes what the image communicates, not just what it is

For decorative images that convey no information (e.g. a background pattern), set `alt=""` explicitly — this tells screen readers to skip it, and it will not be flagged by Markzen SEO's audit.

---

13. Third-Party Script Detector

Markzen SEO → Scripts

Third-party scripts (analytics, chat widgets, advertising pixels, CRM trackers) are the most common cause of poor Core Web Vitals scores. This tool helps you understand exactly what's loading on any page of your site and how.

How to use it

Enter any URL from your site and click Scan. The scanner fetches the page's rendered HTML and analyses every script it finds.

What it detects

| Category | Tools detected | |---|---| | Analytics | Google Analytics 4, Hotjar, Microsoft Clarity | | Tag managers | Google Tag Manager | | Advertising | Facebook Pixel, LinkedIn Insight Tag | | CRM & forms | HubSpot, Marketo (Munchkin) | | Chat widgets | Intercom, Drift, Crisp |

Load type badges

Each detected script shows how it loads:

• ASYNC — loads in parallel with the page, minimal impact
• DEFER — waits until the page is parsed, recommended for non-critical scripts
• SYNC — blocks page rendering until the script loads. High impact on page speed. Scripts in this category should be moved to async or defer if possible.

Impact badges

• LOW — minimal effect on page load
• MEDIUM — noticeable effect, worth monitoring
• HIGH — significant effect on Core Web Vitals

This is informational, not prescriptive

Markzen SEO does not remove or block scripts. This tool gives you the visibility to have an informed conversation about which scripts are justified and which are not — a common pain point between marketing teams (who add tracking scripts) and technical teams (who care about page speed).

---

14. Lighthouse / PageSpeed Audit

Markzen SEO → Lighthouse

Lighthouse is Google's open-source tool for measuring web page quality. Markzen SEO runs Lighthouse audits via the free Google PageSpeed Insights API, delivering the same scores and detailed audit breakdowns you'd get from Chrome DevTools — directly inside your WordPress admin.

Four scores

Each audit returns scores from 0–100 across four categories:

| Score | Colour | Meaning | |---|---|---| | 90–100 | 🟢 Green | Good | | 50–89 | 🟡 Amber | Needs improvement | | 0–49 | 🔴 Red | Poor |

• Performance — how fast the page loads for real users. Affected by image sizes, script loading, server response time, render-blocking resources.
• Accessibility — how usable the page is for people using screen readers or other assistive technology. Image alt text, colour contrast, form labels.
• Best Practices — use of HTTPS, absence of known security vulnerabilities, correct HTTP headers.
• SEO — whether the page is correctly configured for search engine crawling. Meta tags, canonical URLs, structured data, robots directives.

Running an audit

Single page audit: Select any page from the dropdown (or leave on Homepage), choose Mobile or Desktop, and click Run audit. Results appear in 15–30 seconds.

Mobile vs Desktop: Run both. Google uses the mobile score for ranking decisions. Desktop typically scores higher. The gap between them reveals how much room there is for mobile optimisation.

Bulk audit: Click Run bulk audit to audit your 20 most-engaged posts automatically. Results arrive one every 30 seconds to respect API rate limits. You can navigate away — it runs in the background.

Audit history

Markzen SEO stores the last 5 audit results per page. The score history shows whether pages are improving, declining, or stable over time.

Lighthouse SEO score column on post list

After running at least one audit for a post, a coloured score badge appears in the Lighthouse SEO column on your WordPress Posts list. Click any badge to re-run the audit for that post.

API key (optional)

Without an API key, Lighthouse audits work but are rate-limited (a few audits per minute). Add a free key in Settings → Advanced to remove rate limits. Get one at [console.cloud.google.com](https://console.cloud.google.com) — it takes about 5 minutes and is free within generous daily limits.

---

15. Exporting Data to CSV

Every major tool in Markzen SEO supports CSV export. The Export CSV button appears in the top-right of each tool page. Exports respect any active filters — exporting from a filtered view gives you exactly what's on screen, not the full database.

| Page | What exports | |---|---| | Posts & Pages | All posts/pages with SEO title status, meta description status, focus keyphrase, noindex flag | | Keyphrases | All keyphrases with the posts using them and duplicate flags | | Broken Links | All link results with status codes, link type, and ignored flag | | Image Audit | All flagged images with post context and Media Library status |

Use cases for marketing teams

• Export Posts & Pages filtered to "missing meta description" → assign to writers as a task list
• Export Keyphrases → review in a spreadsheet to spot cannibalization across a large site
• Export Broken Links filtered to "Broken" → send to the web manager as a fix ticket
• Export the full Posts & Pages list → import into your content calendar tool

---

16. For Website Managers — Weekly SEO Workflow

This workflow takes approximately 15–20 minutes per week and keeps your site's technical SEO consistently healthy.

Every Monday morning

1. Open the Dashboard Check the four stat cards. Compare them to last week. Are the numbers going up or down?

2. Check Site Health If everything is green, move on. If anything is red, click through and address it.

3. Review Broken Links If a scan has run since last week, check for new broken links. Fix internal broken links immediately. Schedule external ones.

4. Check the robots.txt card If it shows "Conflict detected", this is urgent — your SEO configuration is being overridden by a physical file. Fix before anything else.

Every month

Run a Lighthouse bulk audit Click Run bulk audit on the Lighthouse page. Review the results the next day.

Pages with SEO scores below 70 should be investigated and prioritised for improvement. Common culprits: missing meta description, noindex accidentally set, structured data errors, missing alt text.

Review Image Audit Run a fresh image scan. New images uploaded to the site may have been added without alt text, especially if multiple people are editing content.

Export Posts & Pages to CSV Share with the content team as a status report showing what's optimised and what needs attention.

When publishing new content

Ensure every new post has, before it goes live: - SEO title (60 chars or fewer) - Meta description (120–160 chars) - Focus keyphrase set - At least one image with alt text - At least one internal link to existing content

The SEO analysis checklist in the editor gives you a green/amber/red signal for all of these as you write.

---

17. For Marketing Teams — Decision Making with Markzen SEO

Understanding what to optimise first

Use the Posts & Pages table filtered to "missing meta description." These are your lowest-hanging fruit — pages that rank for something already but are likely losing clicks because the search snippet is being auto-generated by Google rather than written by you.

Priority rule: The closer a page is to the top of search results, the more urgent a well-written meta description is. A page in position 4–10 stands to gain the most from a compelling description because it can steal clicks from higher-ranked results.

Using Focus Keyphrases for content strategy

The Keyphrases page gives you a map of what you're currently targeting. Use it to:

1. Find gaps — topics your competitors cover but you haven't targeted yet 2. Fix cannibalization — when two pages target the same keyphrase, they dilute each other. Merge or differentiate. 3. Find your clusters — group keyphrases by topic. If you have 8 posts about "email marketing" but none link to each other, you're missing a chance to signal topical authority.

Using Lighthouse for campaign landing pages

Before launching any paid campaign, run a Lighthouse audit on the landing page: - Performance below 70 = your cost-per-click is probably higher than it needs to be (slow pages have worse Quality Scores in Google Ads) - SEO below 80 = Google may not be crawling or indexing the page correctly - Accessibility below 80 = a significant percentage of your audience may not be able to use the page

Share the Lighthouse report link with your developer as a concrete, number-based brief rather than a subjective "the page feels slow."

Using Broken Links for content audits

Export broken links and cross-reference with your analytics tool (Google Analytics, Plausible, etc.). Any broken link on a high-traffic page is urgently costing you conversions — fix those first.

Preparing data for reporting

Monthly SEO report structure using Markzen SEO exports:

| Section | Source | |---|---| | Content coverage | Posts & Pages CSV — % with meta description and keyphrase set | | Technical health | Site Health page — screenshot or export | | Keyword strategy | Keyphrases CSV — total keyphrases, duplicates resolved | | Page speed | Lighthouse page — average scores, change from last month | | Link health | Broken Links CSV — broken links found and fixed |

---

18. What Markzen SEO Outputs to Your Site

Markzen SEO adds the following to your site's `` on every page. This is the only thing it adds — no JavaScript, no CSS, no tracking.

Meta tags

```html ```

Open Graph (social sharing)

```html ```

Twitter / X Cards

```html ```

Structured data (JSON-LD)

Three `