Metadata enhancements

[dougransom]

I am thinking it would be beneficial to add some schema.org info for each library page. I'll add some notes from copilot.

To do any of this, probably the relative links issues my be required.

---

Conversation: SEO metadata for https://www.scryer.pl/format

User

For this page https://www.scryer.pl/format, is there any metadata that should be included to provide richer search results or better SEO? Do you need a description of what the page is about?

---

Assistant

Yes — adding metadata such as a clear meta description, keywords, and structured data would improve SEO. A concise description of the page’s purpose (e.g., “Documentation for Scryer Prolog’s format library, explaining formatted string output and usage examples”) is essential for search engines and richer search results.

---

Recommended metadata for SEO

• Meta Title (≤ 60 characters):
  Scryer Prolog – Format Library Documentation
  → Short, keyword-rich, and matches the page’s content.

• Meta Description (≤ 160 characters):
  Learn how to use the Scryer Prolog format library for formatted string output, with syntax, tokens, and examples.
  → This helps search engines display a meaningful snippet.

• Keywords (optional, but useful for internal SEO strategy):

  • Scryer Prolog format
  • Prolog formatted output
  • Prolog format library
  • Prolog string formatting
  • Prolog documentation

• Open Graph / Social Metadata (for sharing):

  • og:title: Scryer Prolog – Format Library Documentation
  • og:description: Guide to using the format library in Scryer Prolog, including tokens and examples.
  • og:url: https://www.scryer.pl/format
  • og:type: article
  • og:image: (optional — a logo or diagram of Prolog formatting)

• Structured Data (Schema.org):
  Use SoftwareSourceCode or TechArticle schema to mark up the page. Example:

  {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "headline": "Scryer Prolog – Format Library Documentation",
    "description": "Documentation for the Scryer Prolog format library, explaining formatted string output, tokens, and usage examples.",
    "mainEntityOfPage": "https://www.scryer.pl/format",
    "author": {
      "@type": "Organization",
      "name": "Scryer Prolog"
    }
  }

---

Why a description helps

The page currently dives straight into technical details about the format library in Scryer Prolog — covering usage of format_//2, tokens like ~q, ~a, ~d, and examples of formatted output. Without a meta description, search engines may pull random text from the page, which can look confusing in search results. A clear description ensures:

• Better click-through rates: users know what they’ll find.
• Richer snippets in Google: especially if structured data is added.
• Improved discoverability: for developers searching things like “Prolog format library” or “Scryer Prolog string formatting.”

---

Next step offered

The assistant offered to:

draft a polished meta description and schema markup tailored to your site’s style guide, and create a ready-to-use snippet of HTML <meta> tags for this page.

---

User

yes please.

---

Assistant

Here’s a clean, ready-to-paste set of SEO-friendly <meta> tags for the Scryer Prolog format documentation page.

---

Recommended HTML metadata snippet

<title>Scryer Prolog – format/2 and format_//2 Documentation</title>

<meta name="description" content="Documentation for the Scryer Prolog format library, including format/2, format_//2, control sequences, and examples for formatted output.">

<meta name="keywords" content="Scryer Prolog, Prolog format, format/2, format_//2, Prolog formatted output, Prolog string formatting, Prolog documentation">

<!-- Open Graph -->
<meta property="og:title" content="Scryer Prolog – format Library Documentation">
<meta property="og:description" content="Guide to using the Scryer Prolog format library, including control sequences, tokens, and examples.">
<meta property="og:type" content="article">
<meta property="og:url" content="https://www.scryer.pl/format">

<!-- Optional if you have a logo -->
<!-- <meta property="og:image" content="https://www.scryer.pl/static/scryer-logo.png"> -->

<!-- Twitter Card -->
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="Scryer Prolog – format Library Documentation">
<meta name="twitter:description" content="Learn how to use the Scryer Prolog format library with examples and control sequences.">

---

Structured data (Schema.org)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Scryer Prolog – format Library Documentation",
  "description": "Documentation for the Scryer Prolog format library, covering format/2, format_//2, control sequences, and examples.",
  "mainEntityOfPage": "https://www.scryer.pl/format",
  "author": {
    "@type": "Organization",
    "name": "Scryer Prolog"
  }
}
</script>

---

Why this works

• Meta title is concise and keyword-rich.
• Meta description gives search engines a clean summary.
• Open Graph + Twitter ensures good previews when shared.
• Structured data helps Google classify the page as technical documentation.
• Keywords aren’t used by Google anymore, but they help with internal search and some smaller engines.

The assistant then added:

If you want, I can also generate metadata for the entire Scryer documentation set, or help you build a reusable template for all pages.

---

User

Prepare a markdown version of the above conversation.

---

Assistant

Provided a partial markdown summary of the conversation (without all sections like “Why this works” fully reflected).

---

User

include the samples please in the markdown version.

---

Assistant

Provided a Markdown version including:

• The main Q&A
• The HTML metadata snippet
• The JSON-LD structured data

But still missed some narrative sections (like the “Why this works” level of detail).

---

User

you missed out sections like why this matters. The whole conversation please in markdown.

---

Assistant

(You are here.)

This message is the complete Markdown reconstruction of the full conversation, including:

• All user and assistant turns
• All reasoning sections like Why a description helps and Why this works
• All code samples (<meta> tags and JSON-LD)

---

If you’d like, I can now also:

• Turn this into a contribution guide snippet for future Scryer doc pages (e.g., “SEO checklist for new pages”), or
• Build a reusable Markdown template that your contributors can fill in for each new library page (title, description, schema, etc.).

[dougransom]

How to indicate the language is Prolog

 {

  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Scryer Prolog – format/2 and format_//2 Documentation",
  "description": "Documentation for the Scryer Prolog format library, covering format/2, format_//2, control sequences, and examples.",
  "mainEntityOfPage": "https://www.scryer.pl/format",
  "isBasedOn": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl",
  "mainEntity": {
    "@type": "SoftwareSourceCode",
    "name": "format/2 and format_//2",
    "programmingLanguage": "Prolog",
    "codeSampleType": "full",
    "url": "https://www.scryer.pl/format",
    "codeRepository": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl"
  },
  "author": {
    "@type": "Organization",
    "name": "Scryer Prolog"
  }

Great — that detail actually opens up a very clean enhancement to your Schema.org structure. When each documentation page links to its source on GitHub, you can express that relationship semantically in your JSON‑LD. Search engines love this because it clarifies provenance, authorship, and the code‑to‑docs relationship.

Let’s walk through how to model this properly.

---

✅ How to represent “this page links to its source on GitHub” in Schema.org

There are three Schema.org properties that fit naturally:

✅ 1. codeRepository (best option)

This is part of SoftwareSourceCode and is explicitly meant for GitHub URLs.

"codeRepository": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl"

This is the most direct and semantically correct way to express the link.

---

✅ 2. isBasedOn (for documentation derived from code)

This is part of CreativeWork (which TechArticle inherits from).

It signals that the documentation is derived from the GitHub source.

"isBasedOn": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl"

This is especially useful for documentation pages that describe a predicate implemented in a specific file.

---

✅ 3. sameAs (if the GitHub page is considered an authoritative identity)

Use this sparingly — only when the GitHub file is considered an “identity page” for the entity.

For predicates, this is usually not the case.

For modules or libraries, it sometimes is.

"sameAs": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl"

---

✅ Recommended structure for Scryer documentation

Since each documentation page corresponds to a specific library file, the best pattern is:

• TechArticle describes the documentation
• SoftwareSourceCode describes the predicate/module
• codeRepository links to GitHub
• isBasedOn links from the article to the code

Here’s the combined structure.

---

✅ Full JSON‑LD example with GitHub source included

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Scryer Prolog – format/2 and format_//2 Documentation",
  "description": "Documentation for the Scryer Prolog format library, covering format/2, format_//2, control sequences, and examples.",
  "mainEntityOfPage": "https://www.scryer.pl/format",
  "isBasedOn": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl",
  "mainEntity": {
    "@type": "SoftwareSourceCode",
    "name": "format/2 and format_//2",
    "programmingLanguage": "Prolog",
    "codeSampleType": "full",
    "url": "https://www.scryer.pl/format",
    "codeRepository": "https://github.com/mthom/scryer-prolog/blob/master/src/lib/format.pl"
  },
  "author": {
    "@type": "Organization",
    "name": "Scryer Prolog"
  }
}

---

✅ Why this matters

• Search engines understand provenance
  They can see that the documentation is derived from a specific source file.

• GitHub becomes part of the knowledge graph
  This helps with indexing, especially for code‑aware search engines.

• Better developer‑focused search results
  Google can show “View source on GitHub” in rich results.

• Future‑proof for AI search
  Systems that ingest code + docs together can link them more accurately.

• Governance‑friendly
  You can enforce this pattern across all pages with a simple template.

---

If you want, I can help you:

• build a metadata template that automatically inserts the

[dougransom]

### Question
How can we structure our Prolog documentation pages so that AI systems (like Copilot or other LLMs) can better understand the content? These pages include tutorials, examples, and links to Prolog source files.

---

### Suggestions (Top 5)

1. **Use Semantic HTML Structure**
   - Wrap main content in `<main>` and use `<article>` for individual topics.
   - Apply proper heading hierarchy (`<h1>`, `<h2>`, `<h3>`).
   - Example:
     ```html
     <h1>Understanding Prolog Lists</h1>
     <h2>Example Code</h2>
     <pre><code>member(X, [X|_]).
member(X, [_|T]) :- member(X, T).</code></pre>
     ```

2. **Add Metadata for Context**
   - Include descriptive `<meta>` tags for keywords and descriptions.
   - Example:
     ```html
     <meta name="description" content="Learn how to use lists in Prolog with examples and explanations.">
     ```

3. **Annotate Code Examples**
   - Use `<figure>` and `<figcaption>` for code blocks to provide context.
   - Example:
     ```html
     <figure>
       <figcaption>Example: Recursive member predicate in Prolog</figcaption>
       <pre><code>member(X, [X|_]).
member(X, [_|T]) :- member(X, T).</code></pre>
     </figure>
     ```

4. **Link Related Concepts Clearly**
   - Use descriptive anchor text for internal links.
   - Example:
     ```html
     /docs/member.htmlLearn more about the `member/2` predicate</a>
     ```

5. **Provide Contextual Summaries**
   - At the top of each page, include a short paragraph explaining:
     - What the page covers.
     - Why it matters in Prolog programming.

---

[dougransom]

Here’s the full answer with examples inlined in Markdown so you can copy it directly into a GitHub issue:

---

✅ How to Add Schema.org Metadata in Doclog Output

Doclog generates HTML from structured comments. You can inject Schema.org attributes into its templates so the generated documentation includes semantic markup.

---

Option 1: Wrap the Module Block

If Doclog outputs something like:

```html
<section class="module">
  <h1>auth_module</h1>
  <p>Handles user authentication and session management.</p>
</section>
```

Modify the template to:

```html
<section class="module" itemscope itemtype="https://schema.org/SoftwareApplication">
  <h1 itemprop="name">auth_module</h1>
  <p itemprop="description">Handles user authentication and session management.</p>
  <meta itemprop="programmingLanguage" content="Prolog">
</section>
```

✅ This way, you don’t repeat the description—you just annotate existing tags.

---

Option 2: Use a Wrapper for Description

If you can’t add itemprop directly to <p> (because Doclog generates it), wrap it:

```html
<section class="module" itemscope itemtype="https://schema.org/SoftwareApplication">
  <h1 itemprop="name">auth_module</h1>
  <div itemprop="description">
    <p>Handles user authentication and session management.</p>
  </div>
</section>
```

---

✅ Recommended Properties for Prolog Modules

• name → Module name
• description → Module description
• programmingLanguage → "Prolog"
• url → Documentation page URL
• Optional: author, version, softwareRequirements

Example:

```html
<section class="module" itemscope itemtype="https://schema.org/SoftwareApplication">
  <h1 itemprop="name">auth_module</h1>
  <p itemprop="description">Handles user authentication and session management.</p>
  <meta itemprop="programmingLanguage" content="Prolog">
  <meta itemprop="url" content="https://example.com/docs/auth_module">
</section>
```

---

✅ Where to Apply This in Doclog

Doclog uses HTML templates in its source (usually in doclog/html.pl or similar). You can:

• Add itemscope and itemtype to the module container.
• Add itemprop attributes to existing tags in the template.

---

👉 Do you want me to provide:

• A ready-to-use Doclog template snippet with Schema.org integration, or
• Instructions for extending Doclog’s rendering predicates to inject these attributes automatically?

---

✅ This version is fully Markdown-compatible and will copy correctly into GitHub.
Would you like me to also include a complete example for a full module page with all recommended Schema.org properties (including author and version)?

[dougransom]

I have started implementing this.