=== Titula ===
Contributors: abourri
Tags: table of contents, internal linking, arabic, rtl, readability
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Editorial analysis and reviewable internal link suggestions for your articles, with a table of contents and answer-first components.

== Description ==

Most plugins in this space stop at generating a table of contents. Titula
starts there and then does the two things that actually take an editor's time:
it tells you what is structurally wrong with an article, and it finds places
where your articles could link to each other.

= What makes it different =

**Editorial Readiness.** Open a post and Titula reports five dimensions —
Answer Clarity, Content Structure, Reader Experience, Internal Linking, Search
and AI Readiness — with a plain sentence and a short list of what to fix. It
names specific problems: a skipped heading level, an introduction that buries
the answer, a section running long without a subheading, images missing
dimensions. There is no word-count target, no keyword density and no keyword
repetition in the model, because none of those measure whether an article is
good.

**Internal link suggestions you approve.** Titula reads your published articles
and finds places where one could link to another. Each suggestion shows the
source, the destination, the sentence around it, a score and the reason. You
accept or ignore it.

Accepting one never rewrites your post. The decision is stored and the link is
applied when the page renders, so your content stays exactly as you wrote it
and any choice can be undone. The anchor is always a phrase your article
already contains — nothing is reworded, and no keyword is forced in. Links are
never placed inside existing links, headings, code or captions.

= Arabic and RTL, handled properly =

Measurement built for the Latin alphabet gives wrong answers in Arabic, and
most plugins never notice. PHP's own `str_word_count()` returns zero for Arabic
text, so reading times on Arabic sites are frequently nonsense.

Titula counts by Unicode word boundaries, strips diacritics and the tatweel
before measuring since neither is a letter, discards punctuation-only tokens,
and times Arabic and Latin words at separate adjustable speeds. Heading anchors
stay readable in Arabic instead of collapsing into numbered fragments.

Three optional extras for Arabic publishers:

* **Latin permalink suggestions.** WordPress percent-encodes Arabic slugs, so a
  title becomes a URL of the form `%d8%a7%d9%84`. Valid, but unreadable once
  copied, printed or read aloud. Titula suggests a transliteration in the
  editor with a checkbox to apply it, warns you when the post is published and
  changing it would break existing links, and never changes anything on its
  own. Arabic permalinks are a legitimate choice.
* **Hijri dates,** shown beside the Gregorian date rather than replacing it.
  The machine-readable date in the markup stays Gregorian, as the HTML
  specification requires. Where the `intl` extension is available the Umm
  al-Qura calendar is used; otherwise a tabular calculation, which can differ
  from an announced date by a day, so a manual adjustment is provided.
* **Arabic typography.** Raises line height, which the script needs because
  letters carry taller ascenders and deeper descenders and diacritics sit above
  and below the line. Just as importantly it resets `letter-spacing`: Arabic
  letters join, and spacing them apart pulls the joins open. Themes designed
  for Latin text set letter-spacing on headings routinely, and it looks correct
  in their previews because those previews are in English.

= Reading experience =

* Table of contents from your H2 and H3 headings, with stable anchors that stay
  readable in Latin, Arabic and accented scripts. Long lists collapse behind a
  "View all sections" control.
* Quick Answer, Key Takeaways and Article Summary, shown above the table of
  contents so a reader who wants only the answer finds it first.
* FAQ, facts, pros and cons, steps, checklist, related reading and an author
  box. Every component optional; one with an empty field renders nothing.
* Tables that take their colours from your theme's own palette rather than
  imposing a second one, and that reorganise on a phone instead of asking the
  reader to drag them sideways. A table of three to seven columns becomes one
  card per row, each value labelled with its own column heading. Very wide
  reference tables keep their scroll, because a card that long stops being
  readable. Nothing is ever hidden: a phone reader sees exactly what a desktop
  reader sees.

= Everything is free =

There is no paid version, no upsell, no locked feature and no account.

= Performance =

* Rendered articles are cached and reused until the post or a setting changes.
* Content analysis is manual, batched and resumable. It never runs on a visitor
  request. Also available as `wp titula scan`.
* Stylesheets load only on singular views of a supported post type, split so a
  post with no tables never downloads the table rules. The script loads only
  when the article actually has a table of contents or images.
* No external requests, no tracking, no jQuery.

= Articles built as raw HTML are left alone =

If you publish some articles as a complete, self-contained HTML layout pasted
into a Custom HTML block, Titula detects them and does nothing to them at all:
no table of contents, no heading anchors, no components, no wrapper, and not
even a stylesheet request.

Detection is deliberately cautious, since wrongly skipping an ordinary article
is far worse than wrongly processing one. It looks for signals an ordinary post
never produces: a `style` element in the content, most of the article sitting
inside Custom HTML blocks, or heavy inline styling. A long article containing
one small embed block is not affected.

Every post also carries a Processing control in the editor, in both the block
and classic editors, so you can force either answer. Excluded articles are
still valid destinations for links from elsewhere: leaving an article alone
means not modifying it, not refusing to point at it.

= What Titula does not do =

* It writes no SEO title, meta description, canonical URL or robots directive.
* It produces no structured data, and never modifies schema from another plugin.
* It generates no text and contacts no external service or AI model.
* It cannot promise a ranking, a Google AI Overview placement or a citation in
  any AI assistant. No plugin can, and this one does not claim to.
* It styles nothing outside the article container, so your theme is untouched.

== Installation ==

1. Install through Plugins > Add New, or upload the ZIP.
2. Activate it.
3. Open Settings > Titula and pick one of the four recommended starting points:
   People First, Travel, Technology or Editorial. That is the whole setup.
4. Optional: run a scan from the Titula dashboard to see internal link
   suggestions and editorial health.

Every individual setting is still there under Advanced, but you should not need
it on day one.

== Frequently Asked Questions ==

= Does this replace Rank Math or Yoast? =

No, and it is designed not to. Titula adds no schema and no meta tags. Keep
using your SEO plugin exactly as you do now.

= Will it change my theme or my other pages? =

No. Every CSS rule is scoped inside the article container. Your header, footer,
sidebar, widgets and every page outside the selected post types are untouched.

= Does it modify my post content in the database? =

No. Components and approved internal links are applied when the page renders.
Your content stays exactly as you wrote it, and anything you enable can be
switched off with no trace left behind.

= Does it require Advanced Custom Fields? =

No. Titula uses ACF when it is present and plain post meta when it is not.

= Will it change my Arabic permalinks? =

Only if you tick the box in the editor and save. Nothing happens in bulk,
nothing happens on activation, and the panel warns you first when the post is
already published.

= How accurate is the Hijri date? =

It is calculated, not announced. In most countries the start of a Hijri month
is declared by observation of the crescent, and no formula predicts that. The
settings screen tells you which method your server uses and offers a manual
adjustment of up to two days.

= Does it send my content anywhere? =

No. All analysis runs on your own server. The plugin makes no external requests
of any kind.

= What happens to my data if I uninstall? =

Plugin settings are removed. Editorial decisions stored on individual posts,
such as which link suggestions you accepted, are left in place so that
reinstalling does not lose your work.

= Will it improve my rankings? =

It cannot promise that, and no honest plugin can. What it does is make articles
clearer, better structured and better connected to each other.

== Changelog ==

= 1.0.0 =
* First public release.

== Upgrade Notice ==

= 1.0.0 =
First public release.
