Improve documentation search titles and link previews

docs/configuration/ipv4.md

@@ -1,3 +1,7 @@
+---
+description: Declare IPv4 addresses, prefix lengths, and address lifetimes in netfyr policies.
+---
+
 # IPv4 addresses
 
 Declare addresses as a list under `ipv4.addresses`:

docs/configuration/policies.md

@@ -1,3 +1,7 @@
+---
+description: Select interfaces, name policies, and organize netfyr configuration in YAML files and directories.
+---
+
 # Policy files
 
 A policy has a name, an interface selector under `match`, and configuration

docs/configuration/providers.md

@@ -1,3 +1,7 @@
+---
+description: Declare DHCP and IPv6 router-advertisement providers in netfyr policies. Provider execution is not available yet.
+---
+
 # Dynamic providers
 
 A policy can declare a dynamic provider alongside static configuration.

docs/getting-started.md

@@ -1,3 +1,7 @@
+---
+description: Write your first netfyr policy to select an interface and declare its network configuration.
+---
+
 # Write a policy
 
 Save this example as `office.yaml`:

docs/index.md

@@ -1,10 +1,14 @@
-# netfyr
+---
+title: Linux network configuration
+description: Write and validate Linux network configuration as YAML policies with netfyr.
+---
 
-Write Linux network configuration as YAML policies. Each policy selects an
-interface and describes its configuration.
+# Linux network configuration {#netfyr}
 
-netfyr currently parses and validates policies. It has no command-line tool or
-backend for applying network changes yet.
+Each netfyr policy selects an interface and describes its configuration in YAML.
+
+netfyr currently parses and validates policies. The end-user command-line tool
+for applying network changes is still in development.
 
 [Start with a policy](getting-started.md), then read about
 [policy files](configuration/policies.md) and [IPv4 addresses](configuration/ipv4.md).

docs/reference/fields.md

@@ -1,3 +1,7 @@
+---
+description: Network interface fields, constraints, and JSON schemas for netfyr policies and observed state.
+---
+
 # State fields
 
 Set writable fields in a policy. `type` is also accepted as device metadata; [`match.type`](../configuration/policies.md) selects an interface. Other read-only fields describe observed state.

docs/troubleshooting.md

@@ -1,3 +1,7 @@
+---
+description: Resolve netfyr policy validation errors, including unknown fields, invalid addresses, and duplicate policy names.
+---
+
 # Configuration errors
 
 Validation errors include field paths, including positions in address lists.

mkdocs.yml

@@ -1,5 +1,5 @@
-site_name: netfyr
-site_description: Configure Linux networking with netfyr.
+site_name: netfyr documentation
+site_description: User guides and field reference for writing netfyr network policies in YAML.
 site_url: !ENV [NETFYR_SITE_URL, "https://docs.netfyr.io/"]
 repo_name: netfyr/docs
 repo_url: https://github.com/netfyr/docs
@@ -59,7 +59,7 @@ markdown_extensions:
   - attr_list
   - tables
   - toc:
-      permalink: true
+      permalink: false
   - pymdownx.details
   - pymdownx.highlight:
       pygments_lang_class: true
@@ -83,3 +83,5 @@ extra_css:
 
 extra:
   generator: false
+  social_image: assets/images/netfyr-mesh-1200x630.jpg
+  social_image_alt: Five bracketed network nodes joined in a mesh, with one orange connection on a dark terminal screen.

overrides/main.html

@@ -0,0 +1,35 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+  {{ super() }}
+  {% if page and page.canonical_url %}
+    {% set title = config.site_name %}
+    {% if page.meta.title %}
+      {% set title = page.meta.title ~ " - " ~ config.site_name %}
+    {% elif page.title and not page.is_homepage %}
+      {% set title = (page.title | striptags) ~ " - " ~ config.site_name %}
+    {% endif %}
+    {% set description = page.meta.description | default(config.site_description, true) %}
+    {% set image = config.site_url.rstrip('/') ~ '/' ~ config.extra.social_image %}
+    <meta property="og:type" content="website">
+    <meta property="og:site_name" content="{{ config.site_name | e }}">
+    <meta property="og:title" content="{{ title | e }}">
+    <meta property="og:description" content="{{ description | e }}">
+    <meta property="og:url" content="{{ page.canonical_url | e }}">
+    <meta property="og:image" content="{{ image | e }}">
+    <meta property="og:image:type" content="image/jpeg">
+    <meta property="og:image:width" content="1200">
+    <meta property="og:image:height" content="630">
+    <meta property="og:image:alt" content="{{ config.extra.social_image_alt | e }}">
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:title" content="{{ title | e }}">
+    <meta name="twitter:description" content="{{ description | e }}">
+    <meta name="twitter:image" content="{{ image | e }}">
+    <meta name="twitter:image:alt" content="{{ config.extra.social_image_alt | e }}">
+    {% if page.is_homepage %}
+      <script type="application/ld+json">
+        {{ {"@context": "https://schema.org", "@type": "WebSite", "name": config.site_name, "url": page.canonical_url} | tojson }}
+      </script>
+    {% endif %}
+  {% endif %}
+{% endblock %}

scripts/sync_core.py

@@ -98,6 +98,9 @@ def rows(node, prefix=""):
 
 def render(schemas, commit):
     lines = [
+        "---",
+        "description: Network interface fields, constraints, and JSON schemas for netfyr policies and observed state.",
+        "---", "",
         "# State fields", "",
         "Set writable fields in a policy. `type` is also accepted as device metadata; "
         "[`match.type`](../configuration/policies.md) selects an interface. "