Site: page titles, descriptions, social previews and structured data #17

Part of the SEO epic: gudoshnikovn/libphash#51

The site at https://gudoshnikovn.github.io/python-libphash/ has the same gaps as the C library's site (libphash#52): one description for every page ("Perceptual image hashing in Python: the binding of the libphash C library" on all 24 pages), titles from navigation labels ("Home - python-libphash", "Hashing many images - python-libphash"), no Open Graph, Twitter or structured data. Python users search for perceptual hashing far more often than C users do, so this site is the one most searches can reach, and its job is to answer the Python question and hand the reader on to libphash's site for the theory.

Zensical 0.0.68 has what this needs, no post-build step: theme.custom_dir for an override directory, the extrahead block in base.html, and page.meta.title / page.meta.description from front matter in the <title> and <meta name="description">.

Page metadata

• title and description front matter on every page in docs/, worded the way people search: "perceptual image hash in Python", "find duplicate images in Python", "imagehash alternative", "hash images from numpy / Pillow / OpenCV", "hash a directory on all CPUs". Title up to 60 characters, description 120–160, the query's words first.
• Front page: a title that says what the package is ("python-libphash: perceptual image hashing for Python") and, near the top, that it installs as python-libphash and imports as libphash, and that it is not pHash.org's library (Debian/Ubuntu libphash0) nor the phash/imagehash packages.
• Pages made from a snippet (changelog, contributing, security, migration) and the API pages (mkdocstrings) carry the front matter in their wrapper in docs/.
• One h1 per page that matches the title's wording.
• The strict build (or tests/test_docs.py) fails on a page without a title or description, on a description outside 120–160 characters, and on a description or title another page also has.

Social previews and structured data (overrides/main.html, extrahead)

• og:title, og:description, og:url (the canonical URL), og:type, og:site_name, og:image with its size and alt text; twitter:card = summary_large_image.
• A 1200×630 preview image generated in the repository, in the C site's style (whichever libphash#52 settles on: one per site or one per page); the same image as the repository's social preview on GitHub.
• JSON-LD SoftwareSourceCode on the front page: name, description, programmingLanguage: Python, codeRepository, license, version (from the package), url of the PyPI page, isBasedOn libphash's repository and site.
• JSON-LD TechArticle on guide pages and BreadcrumbList from the navigation path, the same shape as libphash's.
• Checked after the deploy: Google's Rich Results Test (no errors), an OG preview (Telegram, Slack or opengraph.xyz), and Lighthouse SEO 100 on the front page and one guide page.

Leading readers to libphash's site

• Theory is not copied from the C site: pages link to it (two copies of the same text on two sites split their ranking).
• Every algorithm the site names links to its page on libphash's site, with the algorithm's name as the link text, not "here": the Algorithm members in the API reference (docstrings), the configuring, loading, batch and storing guides.
• Each guide page that sets or compares hashes links the relevant theory page (comparing, choosing a threshold, choosing an algorithm); today only the front page and five guides do.
• "Finding duplicate images" task page (libphash#53 leaves open which site carries it): this site, if decided there, with the Python code from examples/ and the thresholds and theory linked on libphash's site.
• A comparison with other Python libraries is libphash's (libphash#47, the binding benchmarks no other library); this site links to it once it exists.

PyPI and GitHub

• Documentation = "https://gudoshnikovn.github.io/python-libphash/" in [project.urls] (a well-known PyPI label, shown with its icon); decide whether Homepage stays on GitHub. Check whether tools/audit.py or the tests compare the Project-URL entries.
• README (the PyPI long description): the first paragraph states what the package is and what it is for in the words people search; the libphash link points to its site, not its repository.
• keywords: add near-duplicate, image similarity, ahash, whash, numpy, pillow.
• PyPI long description and repository description are current: search mirrors of this repository still show 1.10.4-era text ("C library (v1.10.4)", "libpng/spng"). Mirrors (libraries.io, piwheels and the like) refresh from PyPI with the next release.
• Repository description matches the README's first sentence; topics as broad as libphash's: image-hashing, image-similarity, duplicate-detection, near-duplicate, ahash, dhash, whash, numpy, pillow.

Not in this issue

robots.txt for gudoshnikovn.github.io, Search Console and Bing Webmaster Tools (covering both sites), conda-forge, awesome lists, articles: the epic's work outside the repositories. Measuring: Search Console 4 and 12 weeks after the deploy, recorded on the epic.

The site deploys on a release tag, so the changes ship with the next binding release; the PyPI metadata ships with its wheels.