fix: convert definition lists to HTML dl elements

ctauchen · claude · ctauchen · commit dc9500078b69 · 2026-03-10T17:12:58.000Z
MDX/Docusaurus does not support the kramdown-style definition list
syntax (term\n: definition). Convert all instances to standard HTML
&lt;dl&gt;/&lt;dt&gt;/&lt;dd&gt; elements which render correctly in MDX without
requiring any additional remark plugins.

Affected files:
- calico/networking/openstack/neutron-api.mdx
- calico-cloud/reference/architecture/design/l3-interconnect-fabric.mdx
- versioned copies of the above (3.29, 3.30, 3.31, calico-cloud-22-2)

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/calico-cloud/reference/architecture/design/l3-interconnect-fabric.mdx b/calico-cloud/reference/architecture/design/l3-interconnect-fabric.mdx
@@ -142,33 +142,28 @@ comfortable with advanced BGP design.
 
 These considerations are:
 
-AS continuity
-
-: or _AS puddling_ Any router in an AS _must_ be able to communicate
-with any other router in that same AS without transiting another AS.
-
-Next hop behavior
-
-: By default BGP routers do not change the _next hop_ of a route if it
-is peering with another router in its same AS. The inverse is also
-true, a BGP router will set itself as the _next hop_ of a route if
-it is peering with a router in another AS.
-
-Route reflection
-
-: All BGP routers in a given AS must _peer_ with all the other routers
-in that AS. This is referred to a _complete BGP mesh_. This can
-become problematic as the number of routers in the AS scales up. The
-use of _route reflectors_ reduce the need for the complete BGP mesh.
-However, route reflectors also have scaling considerations.
-
-Endpoints
-
-: In a $[prodname] network, each endpoint is a route. Hardware networking
-platforms are constrained by the number of routes they can learn.
-This is usually in range of 10,000's or 100,000's of routes. Route
-aggregation can help, but that is usually dependent on the
-capabilities of the scheduler used by the orchestration software.
+<dl>
+  <dt>AS continuity</dt>
+  <dd>or <em>AS puddling</em> Any router in an AS <em>must</em> be able to communicate
+  with any other router in that same AS without transiting another AS.</dd>
+  <dt>Next hop behavior</dt>
+  <dd>By default BGP routers do not change the <em>next hop</em> of a route if it
+  is peering with another router in its same AS. The inverse is also
+  true, a BGP router will set itself as the <em>next hop</em> of a route if
+  it is peering with a router in another AS.</dd>
+  <dt>Route reflection</dt>
+  <dd>All BGP routers in a given AS must <em>peer</em> with all the other routers
+  in that AS. This is referred to a <em>complete BGP mesh</em>. This can
+  become problematic as the number of routers in the AS scales up. The
+  use of <em>route reflectors</em> reduce the need for the complete BGP mesh.
+  However, route reflectors also have scaling considerations.</dd>
+  <dt>Endpoints</dt>
+  <dd>In a $[prodname] network, each endpoint is a route. Hardware networking
+  platforms are constrained by the number of routes they can learn.
+  This is usually in range of 10,000's or 100,000's of routes. Route
+  aggregation can help, but that is usually dependent on the
+  capabilities of the scheduler used by the orchestration software.</dd>
+</dl>
 
 A deeper discussion of these considerations can be found in the IP
 Fabric Design Considerations\_ appendix.
diff --git a/calico-cloud_versioned_docs/version-22-2/reference/architecture/design/l3-interconnect-fabric.mdx b/calico-cloud_versioned_docs/version-22-2/reference/architecture/design/l3-interconnect-fabric.mdx
@@ -142,33 +142,28 @@ comfortable with advanced BGP design.
 
 These considerations are:
 
-AS continuity
-
-: or _AS puddling_ Any router in an AS _must_ be able to communicate
-with any other router in that same AS without transiting another AS.
-
-Next hop behavior
-
-: By default BGP routers do not change the _next hop_ of a route if it
-is peering with another router in its same AS. The inverse is also
-true, a BGP router will set itself as the _next hop_ of a route if
-it is peering with a router in another AS.
-
-Route reflection
-
-: All BGP routers in a given AS must _peer_ with all the other routers
-in that AS. This is referred to a _complete BGP mesh_. This can
-become problematic as the number of routers in the AS scales up. The
-use of _route reflectors_ reduce the need for the complete BGP mesh.
-However, route reflectors also have scaling considerations.
-
-Endpoints
-
-: In a $[prodname] network, each endpoint is a route. Hardware networking
-platforms are constrained by the number of routes they can learn.
-This is usually in range of 10,000's or 100,000's of routes. Route
-aggregation can help, but that is usually dependent on the
-capabilities of the scheduler used by the orchestration software.
+<dl>
+  <dt>AS continuity</dt>
+  <dd>or <em>AS puddling</em> Any router in an AS <em>must</em> be able to communicate
+  with any other router in that same AS without transiting another AS.</dd>
+  <dt>Next hop behavior</dt>
+  <dd>By default BGP routers do not change the <em>next hop</em> of a route if it
+  is peering with another router in its same AS. The inverse is also
+  true, a BGP router will set itself as the <em>next hop</em> of a route if
+  it is peering with a router in another AS.</dd>
+  <dt>Route reflection</dt>
+  <dd>All BGP routers in a given AS must <em>peer</em> with all the other routers
+  in that AS. This is referred to a <em>complete BGP mesh</em>. This can
+  become problematic as the number of routers in the AS scales up. The
+  use of <em>route reflectors</em> reduce the need for the complete BGP mesh.
+  However, route reflectors also have scaling considerations.</dd>
+  <dt>Endpoints</dt>
+  <dd>In a $[prodname] network, each endpoint is a route. Hardware networking
+  platforms are constrained by the number of routes they can learn.
+  This is usually in range of 10,000's or 100,000's of routes. Route
+  aggregation can help, but that is usually dependent on the
+  capabilities of the scheduler used by the orchestration software.</dd>
+</dl>
 
 A deeper discussion of these considerations can be found in the IP
 Fabric Design Considerations\_ appendix.
@@ -215,7 +210,9 @@ Within the rack, the configuration is the same for both variants, and is
 somewhat different than the configuration north of the ToR.
 
 Every router within the rack, which, in the case of $[prodname] is every
+{/* vale Vale.Repetition = NO */}
 compute server, shares the same AS as the ToR that they are connected
+{/* vale Vale.Repetition = YES */}
 to. That connection is in the form of an Ethernet switching layer. Each
 router in the rack must be directly connected to enable the AS to remain
 contiguous. The ToR's _router_ function is then connected to that
@@ -407,8 +404,10 @@ for two _networks_ that are not directly connected, but only connected
 through another _network_ or AS number will not work without a lot of
 policy changes to the BGP routers.
 
+{/* vale Vale.Repetition = NO */}
 Another corollary of that rule is that a BGP router will not propagate a
 route to a peer if the route has an AS in its path that is the same AS
+{/* vale Vale.Repetition = YES */}
 as the peer. This prevents loops from forming in the network. The effect
 of this prevents two routers in the same AS from transiting another
 router (either in that AS or not).
diff --git a/calico/networking/openstack/neutron-api.mdx b/calico/networking/openstack/neutron-api.mdx
@@ -72,10 +72,11 @@ In $[prodname], these roles for the Neutron subnet are preserved in their
 entirety. All properties associated with these Neutron subnets are
 preserved and remain meaningful except for:
 
-`host_routes`
-
-: These have no effect, as the compute nodes will route traffic
-immediately after it egresses the VM.
+<dl>
+  <dt><code>host_routes</code></dt>
+  <dd>These have no effect, as the compute nodes will route traffic
+  immediately after it egresses the VM.</dd>
+</dl>
 
 ## Ports
 
@@ -86,27 +87,27 @@ shared layer 3 network that $[prodname] builds in Neutron.
 
 All properties on a port work as normal, except for the following:
 
-`network_id`
-
-: The network ID still controls which Neutron network the port is
-attached to, and therefore still controls which Neutron subnets it
-will be placed in. However, as per the [note above](#networks),
-the Neutron network that a port is placed in does not affect which
-machines in the deployment it can contact.
+<dl>
+  <dt><code>network_id</code></dt>
+  <dd>The network ID still controls which Neutron network the port is
+  attached to, and therefore still controls which Neutron subnets it
+  will be placed in. However, as per the <a href="#networks">note above</a>,
+  the Neutron network that a port is placed in does not affect which
+  machines in the deployment it can contact.</dd>
+</dl>
 
 ### Extended Attributes: Port Binding Attributes
 
 The `binding:host-id` attribute works as normal. The following notes
 apply to the other attributes:
 
-`binding:profile`
-
-: This is unused in $[prodname].
-
-`binding:vnic_type`
-
-: This field, if used, **must** be set to `normal`. If set to any
-other value, $[prodname] will not correctly function!
+<dl>
+  <dt><code>binding:profile</code></dt>
+  <dd>This is unused in $[prodname].</dd>
+  <dt><code>binding:vnic_type</code></dt>
+  <dd>This field, if used, <strong>must</strong> be set to <code>normal</code>. If set to any
+  other value, $[prodname] will not correctly function!</dd>
+</dl>
 
 ## Quotas
 
diff --git a/calico_versioned_docs/version-3.29/networking/openstack/neutron-api.mdx b/calico_versioned_docs/version-3.29/networking/openstack/neutron-api.mdx
@@ -72,10 +72,11 @@ In $[prodname], these roles for the Neutron subnet are preserved in their
 entirety. All properties associated with these Neutron subnets are
 preserved and remain meaningful except for:
 
-`host_routes`
-
-: These have no effect, as the compute nodes will route traffic
-immediately after it egresses the VM.
+<dl>
+  <dt><code>host_routes</code></dt>
+  <dd>These have no effect, as the compute nodes will route traffic
+  immediately after it egresses the VM.</dd>
+</dl>
 
 ## Ports
 
@@ -86,27 +87,27 @@ shared layer 3 network that $[prodname] builds in Neutron.
 
 All properties on a port work as normal, except for the following:
 
-`network_id`
-
-: The network ID still controls which Neutron network the port is
-attached to, and therefore still controls which Neutron subnets it
-will be placed in. However, as per the [note above](#networks),
-the Neutron network that a port is placed in does not affect which
-machines in the deployment it can contact.
+<dl>
+  <dt><code>network_id</code></dt>
+  <dd>The network ID still controls which Neutron network the port is
+  attached to, and therefore still controls which Neutron subnets it
+  will be placed in. However, as per the <a href="#networks">note above</a>,
+  the Neutron network that a port is placed in does not affect which
+  machines in the deployment it can contact.</dd>
+</dl>
 
 ### Extended Attributes: Port Binding Attributes
 
 The `binding:host-id` attribute works as normal. The following notes
 apply to the other attributes:
 
-`binding:profile`
-
-: This is unused in $[prodname].
-
-`binding:vnic_type`
-
-: This field, if used, **must** be set to `normal`. If set to any
-other value, $[prodname] will not correctly function!
+<dl>
+  <dt><code>binding:profile</code></dt>
+  <dd>This is unused in $[prodname].</dd>
+  <dt><code>binding:vnic_type</code></dt>
+  <dd>This field, if used, <strong>must</strong> be set to <code>normal</code>. If set to any
+  other value, $[prodname] will not correctly function!</dd>
+</dl>
 
 ## Quotas
 
@@ -139,6 +140,42 @@ model. See [Detailed semantics](semantics.mdx) for a
 fuller explanation. Where isolation of a particular Neutron network is
 desired, we recommend expressing that through security group rules.
 
+## QoS
+
+Calico for OpenStack implements some Neutron QoS policy fields: the `max_kbps`
+and `max_burst_kbps` fields of bandwidth limit rules, and the `max_kpps` field
+of packet rate limit rules.  Calico also honours the `direction` field of these
+rules, so these limits can be set independently for both ingress and egress
+directions.
+
+:::note
+
+There is uncertainty as to whether `max_burst_kbps` is intended to configure
+the burst *rate* or the burst *size*.  Calico interprets it as the burst *rate*
+and honours `neutron.conf` fields for configuring the burst *size*.
+
+:::
+
+There are also new Calico Neutron driver settings (cluster-wide, set in `neutron.conf`):
+
+- `[calico] max_ingress_connections_per_port` for imposing a maximum number of
+  ingress connections per Neutron port, and
+
+- `[calico] max_egress_connections_per_port` for imposing a maximum number of
+  egress connections per Neutron port.
+
+- `[calico] ingress_burst_kbits`, if non-zero, configures the maximum allowed
+  burst at peakrate, in the ingress direction.
+
+- `[calico] egress_burst_kbits`, if non-zero, configures the maximum allowed
+  burst at peakrate, in the egress direction.
+
+- `[calico] ingress_minburst_bytes`, if non-zero, configures the minimum burst
+  size for peakrate data, in the ingress direction.
+
+- `[calico] egress_minburst_bytes`, if non-zero, configures the minimum burst
+  size for peakrate data, in the egress direction.
+
 ## Load Balancer as a Service
 
 Load Balancer as a Service (LBaaS) does not function in a $[prodname] network. Any
diff --git a/calico_versioned_docs/version-3.30/networking/openstack/neutron-api.mdx b/calico_versioned_docs/version-3.30/networking/openstack/neutron-api.mdx
@@ -72,10 +72,11 @@ In $[prodname], these roles for the Neutron subnet are preserved in their
 entirety. All properties associated with these Neutron subnets are
 preserved and remain meaningful except for:
 
-`host_routes`
-
-: These have no effect, as the compute nodes will route traffic
-immediately after it egresses the VM.
+<dl>
+  <dt><code>host_routes</code></dt>
+  <dd>These have no effect, as the compute nodes will route traffic
+  immediately after it egresses the VM.</dd>
+</dl>
 
 ## Ports
 
@@ -86,27 +87,27 @@ shared layer 3 network that $[prodname] builds in Neutron.
 
 All properties on a port work as normal, except for the following:
 
-`network_id`
-
-: The network ID still controls which Neutron network the port is
-attached to, and therefore still controls which Neutron subnets it
-will be placed in. However, as per the [note above](#networks),
-the Neutron network that a port is placed in does not affect which
-machines in the deployment it can contact.
+<dl>
+  <dt><code>network_id</code></dt>
+  <dd>The network ID still controls which Neutron network the port is
+  attached to, and therefore still controls which Neutron subnets it
+  will be placed in. However, as per the <a href="#networks">note above</a>,
+  the Neutron network that a port is placed in does not affect which
+  machines in the deployment it can contact.</dd>
+</dl>
 
 ### Extended Attributes: Port Binding Attributes
 
 The `binding:host-id` attribute works as normal. The following notes
 apply to the other attributes:
 
-`binding:profile`
-
-: This is unused in $[prodname].
-
-`binding:vnic_type`
-
-: This field, if used, **must** be set to `normal`. If set to any
-other value, $[prodname] will not correctly function!
+<dl>
+  <dt><code>binding:profile</code></dt>
+  <dd>This is unused in $[prodname].</dd>
+  <dt><code>binding:vnic_type</code></dt>
+  <dd>This field, if used, <strong>must</strong> be set to <code>normal</code>. If set to any
+  other value, $[prodname] will not correctly function!</dd>
+</dl>
 
 ## Quotas
 
diff --git a/calico_versioned_docs/version-3.31/networking/openstack/neutron-api.mdx b/calico_versioned_docs/version-3.31/networking/openstack/neutron-api.mdx
