diff --git a/docs/assets/images/netfyr-mesh-1200x630.jpg b/docs/assets/images/netfyr-mesh-1200x630.jpg new file mode 100644 index 0000000..19b59fa Binary files /dev/null and b/docs/assets/images/netfyr-mesh-1200x630.jpg differ diff --git a/docs/configuration/ipv4.md b/docs/configuration/ipv4.md index be0eb23..dcf6541 100644 --- a/docs/configuration/ipv4.md +++ b/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`: diff --git a/docs/configuration/policies.md b/docs/configuration/policies.md index 3dde303..9b41c4c 100644 --- a/docs/configuration/policies.md +++ b/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 diff --git a/docs/configuration/providers.md b/docs/configuration/providers.md index 1617c04..00c4791 100644 --- a/docs/configuration/providers.md +++ b/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. diff --git a/docs/getting-started.md b/docs/getting-started.md index 5d9652c..4e2b694 100644 --- a/docs/getting-started.md +++ b/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`: diff --git a/docs/index.md b/docs/index.md index b6c346a..3cdbec2 100644 --- a/docs/index.md +++ b/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). diff --git a/docs/reference/fields.md b/docs/reference/fields.md index 2675896..06b0ad2 100644 --- a/docs/reference/fields.md +++ b/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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 714d9f9..612effc 100644 --- a/docs/troubleshooting.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 5c0e575..ed2f85e 100644 --- a/mkdocs.yml +++ b/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. diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 0000000..e419ff8 --- /dev/null +++ b/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 %} + + + + + + + + + + + + + + + + {% if page.is_homepage %} + + {% endif %} + {% endif %} +{% endblock %} diff --git a/scripts/sync_core.py b/scripts/sync_core.py index e054188..6afa6a1 100644 --- a/scripts/sync_core.py +++ b/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. "