chore(ia): XPath docs

files/en-us/mdn/writing_guidelines/page_structures/page_types/page_type_key/index.md

@@ -187,7 +187,7 @@ This section lists `page-type` values for pages under [Web/Manifest](/en-US/docs
 
 This section lists `page-type` values for pages under [Web/XPath](/en-US/docs/Web/XPath). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values.
 
-- `xpath-function`: a function, like [`ceiling()`](/en-US/docs/Web/XPath/Functions/ceiling)
+- `xpath-function`: a function, like [`ceiling()`](/en-US/docs/Web/XPath/Reference/Functions/ceiling)
 
 ### XSLT page types
 

files/en-us/mozilla/firefox/releases/3.6/index.md

@@ -84,7 +84,7 @@ Gecko 1.9.2 introduces JavaScript 1.8.2, which adds a number of language feature
 ### XPath
 
 - The choose() XPath method is now supported
-  - : The [`choose()`](/en-US/docs/Web/XPath/Functions/choose) method is now supported by our implementation of [XPath](/en-US/docs/Web/XPath).
+  - : The [`choose()`](/en-US/docs/Web/XPath/Reference/Functions/choose) method is now supported by our implementation of [XPath](/en-US/docs/Web/XPath).
 
 ## For XUL and add-on developers
 

files/en-us/mozilla/firefox/releases/3.6/updating_extensions/index.md

@@ -25,7 +25,7 @@ The DOM Level 2 views to HTML and XHTML documents are now unified per HTML 5.
 - `document.createElementNS(null, "FOO")` no longer creates an HTML element node in HTML documents. `document.createElement("FOO")`
   or `document.createElementNS("http://www.w3.org/1999/xhtml", "foo")` continue
   to work in HTML documents.
-- The [`name`](/en-US/docs/Web/XPath/Functions/name) and the [`local-name`](/en-US/docs/Web/XPath/Functions/local-name) functions in XPath returns the name of HTML elements in lower case. Previously, in HTML documents, they returned it in upper case.
+- The [`name`](/en-US/docs/Web/XPath/Reference/Functions/name) and the [`local-name`](/en-US/docs/Web/XPath/Reference/Functions/local-name) functions in XPath returns the name of HTML elements in lower case. Previously, in HTML documents, they returned it in upper case.
 
 The most probable upgrade problem is the pattern `if (elt.localName === "FOO")`.
 

files/en-us/web/api/document/creatensresolver/index.md

@@ -38,4 +38,4 @@ createNSResolver(nodeResolver)
 ## See also
 
 - {{domxref("Document.evaluate()")}}
-- [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Introduction_to_using_XPath_in_JavaScript)
+- [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Guides/Introduction_to_using_XPath_in_JavaScript)

files/en-us/web/api/document/evaluate/index.md

@@ -142,7 +142,7 @@ context node, document.body. If the "." was left out (leaving `//h2`) the
 query would start from the root node (`html`) which would be more
 wasteful.)
 
-See [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Introduction_to_using_XPath_in_JavaScript) for more information.
+See [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Guides/Introduction_to_using_XPath_in_JavaScript) for more information.
 
 ### Getting element by xml:id
 

files/en-us/web/xpath/guides/comparison_with_css_selectors/index.md

@@ -0,0 +1,17 @@
+---
+title: Comparison of CSS Selectors and XPath
+slug: Web/XPath/Guides/Comparison_with_CSS_selectors
+page-type: guide
+sidebar: xsltsidebar
+---
+
+This article seeks to document the difference between CSS Selectors and XPath for web developers to be able to better choose the right tool for the right job.
+
+| [XPath feature](/en-US/docs/Web/XPath)                                                                                                                                                                     | [CSS equivalent](/en-US/docs/Web/CSS/CSS_selectors)                                                                                                          |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`ancestor`](/en-US/docs/Web/XPath/Reference/Axes#ancestor), [`parent`](/en-US/docs/Web/XPath/Reference/Axes#parent) or [`preceding-sibling`](/en-US/docs/Web/XPath/Reference/Axes#preceding-sibling) axis | {{CSSxRef(":has",":has()")}} selector                                                                                                                        |
+| [`attribute`](/en-US/docs/Web/XPath/Reference/Axes#attribute) axis                                                                                                                                         | [Attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors)                                                                                               |
+| [`child`](/en-US/docs/Web/XPath/Reference/Axes#child) axis                                                                                                                                                 | [Child combinator](/en-US/docs/Web/CSS/Child_combinator)                                                                                                     |
+| [`descendant`](/en-US/docs/Web/XPath/Reference/Axes#descendant) axis                                                                                                                                       | [Descendant combinator](/en-US/docs/Web/CSS/Descendant_combinator)                                                                                           |
+| [`following-sibling`](/en-US/docs/Web/XPath/Reference/Axes#following-sibling) axis                                                                                                                         | [Subsequent-sibling combinator](/en-US/docs/Web/CSS/Subsequent-sibling_combinator) or [Next-sibling combinator](/en-US/docs/Web/CSS/Next-sibling_combinator) |
+| [`self`](/en-US/docs/Web/XPath/Reference/Axes#self) axis                                                                                                                                                   | {{CSSxRef(":scope")}} or {{CSSxRef(":host")}} selector                                                                                                       |

files/en-us/web/xpath/guides/index.md

@@ -0,0 +1,16 @@
+---
+title: XPath guides
+short-title: Guides
+slug: Web/XPath/Guides
+page-type: listing-page
+sidebar: xsltsidebar
+---
+
+This page lists guides for XPath.
+They're intended to help you understand what kinds of things are possible using XPath in JavaScript, and highlight the similarities with CSS selectors.
+
+{{SubPagesWithSummaries}}
+
+## See also
+
+- [XPath reference](/en-US/docs/Web/XPath/Reference)

files/en-us/web/xpath/introduction_to_using_xpath_in_javascript/index.md → files/en-us/web/xpath/guides/introduction_to_using_xpath_in_javascript/index.md

@@ -1,6 +1,6 @@
 ---
 title: Introduction to using XPath in JavaScript
-slug: Web/XPath/Introduction_to_using_XPath_in_JavaScript
+slug: Web/XPath/Guides/Introduction_to_using_XPath_in_JavaScript
 page-type: guide
 sidebar: xsltsidebar
 ---
@@ -80,7 +80,7 @@ We obtain the returned value of the expression by accessing the following proper
 
 ##### Example
 
-The following uses the XPath expression [`count(//p)`](/en-US/docs/Web/XPath/Functions/count) to obtain the number of `<p>` elements in an HTML document:
+The following uses the XPath expression [`count(//p)`](/en-US/docs/Web/XPath/Reference/Functions/count) to obtain the number of `<p>` elements in an HTML document:
 
 ```js
 const paragraphCount = document.evaluate(
@@ -323,11 +323,11 @@ Another approach to match default elements in a non-null namespace (and one whic
 
 If one wishes to provide flexibility in namespaces (as they are intended) by not necessarily requiring a particular prefix to be used when finding a namespaced element or attribute, one must use special techniques.
 
-While one can adapt the approach in the above section to test for namespaced elements regardless of the prefix chosen (using [`local-name()`](/en-US/docs/Web/XPath/Functions/local-name) in combination with [`namespace-uri()`](/en-US/docs/Web/XPath/Functions/namespace-uri) instead of [`name()`](/en-US/docs/Web/XPath/Functions/name)), a more challenging situation occurs, however, if one wishes to grab an element with a particular namespaced attribute in a predicate (given the absence of implementation-independent variables in XPath 1.0).
+While one can adapt the approach in the above section to test for namespaced elements regardless of the prefix chosen (using [`local-name()`](/en-US/docs/Web/XPath/Reference/Functions/local-name) in combination with [`namespace-uri()`](/en-US/docs/Web/XPath/Reference/Functions/namespace-uri) instead of [`name()`](/en-US/docs/Web/XPath/Reference/Functions/name)), a more challenging situation occurs, however, if one wishes to grab an element with a particular namespaced attribute in a predicate (given the absence of implementation-independent variables in XPath 1.0).
 
 For example, one might try (incorrectly) to grab an element with a namespaced attribute as follows: `const xpathLink = someElements[local-name(@*)="href" and namespace-uri(@*)='http://www.w3.org/1999/xlink'];`
 
-This could inadvertently grab some elements if one of its attributes existed that had a local name of `href`, but it was a different attribute which had the targeted (XLink) namespace (instead of [`@href`](/en-US/docs/Web/XPath/Axes#attribute)).
+This could inadvertently grab some elements if one of its attributes existed that had a local name of `href`, but it was a different attribute which had the targeted (XLink) namespace (instead of [`@href`](/en-US/docs/Web/XPath/Reference/Axes#attribute)).
 
 In order to accurately grab elements with the XLink `@href` attribute (without also being confined to predefined prefixes in a namespace resolver), one could obtain them as follows:
 

files/en-us/web/xpath/snippets/index.md → files/en-us/web/xpath/guides/snippets/index.md

@@ -1,6 +1,6 @@
 ---
 title: XPath snippets
-slug: Web/XPath/Snippets
+slug: Web/XPath/Guides/Snippets
 page-type: guide
 sidebar: xsltsidebar
 ---
@@ -152,4 +152,4 @@ function getXPathForElement(el, xml) {
 
 ## See also
 
-- [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Introduction_to_using_XPath_in_JavaScript)
+- [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Guides/Introduction_to_using_XPath_in_JavaScript)

files/en-us/web/xpath/index.md

@@ -11,30 +11,24 @@ XPath is mainly used in [XSLT](/en-US/docs/Web/XSLT), but can also be used as a
 
 XPath uses a path notation (as in URLs) for navigating through the hierarchical structure of an XML document. It uses a non-XML syntax so that it can be used in URIs and XML attribute values.
 
-> [!NOTE]
-> Support for XPath varies widely; it's supported reasonably well in Firefox (although there are no plans to improve support further), while other browsers implement it to a lesser extent, if at all. If you need a polyfill, you may consider [js-xpath](https://pilotfiber.dl.sourceforge.net/project/js-xpath/js-xpath/1.0.0/xpath.js) or [wicked-good-xpath](https://github.com/google/wicked-good-xpath).
+## Guides
 
-## Documentation
-
-- [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Introduction_to_using_XPath_in_JavaScript)
+- [Introduction to using XPath in JavaScript](/en-US/docs/Web/XPath/Guides/Introduction_to_using_XPath_in_JavaScript)
   - : Describes a non-XSLT use of XPath.
-- [XPath:Axes](/en-US/docs/Web/XPath/Axes)
-  - : List and definition of the axes defined in the XPath specification. Axes are used to describe the relationships between nodes.
-- [XPath:Functions](/en-US/docs/Web/XPath/Functions)
-  - : List and description of the core XPath functions and XSLT-specific additions to XPath.
-- [Transforming XML with XSLT](/en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT)
-  - : XSLT uses XPath to address code segments in an XML document that it wishes to transform.
-- [XPath snippets](/en-US/docs/Web/XPath/Snippets)
+- [XPath snippets](/en-US/docs/Web/XPath/Guides/Snippets)
   - : These are JavaScript utility functions, that can be used in your own code, based on [DOM Level 3 XPath](https://www.w3.org/TR/DOM-Level-3-XPath/) APIs.
-- [What is XSLT?](https://www.xml.com/pub/a/2000/08/holman/)
-  - : This extensive introduction to XSLT and XPath assumes no prior knowledge of the technologies, and guides the reader through background, context, structure, concepts, and introductory terminology.
 
-## Tools
+## Reference
 
-- [XPath tester](https://extendsclass.com/xpath-tester.html)
-  - : An online XPath Builder/Debugger.
+- [XPath:Axes](/en-US/docs/Web/XPath/Reference/Axes)
+  - : List and definition of the axes defined in the XPath specification. Axes are used to describe the relationships between nodes.
+- [XPath:Functions](/en-US/docs/Web/XPath/Reference/Functions)
+  - : List and description of the core XPath functions and XSLT-specific additions to XPath.
 
-## Related Topics
+## See also
 
 - [XSLT](/en-US/docs/Web/XSLT), [XML](/en-US/docs/Web/XML), [DOM](/en-US/docs/Web/API/Document_Object_Model)
-- [Comparison of CSS Selectors and XPath](/en-US/docs/Web/XPath/Comparison_with_CSS_selectors)
+- [Transforming XML with XSLT](/en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT)
+- [Comparison of CSS Selectors and XPath](/en-US/docs/Web/XPath/Guides/Comparison_with_CSS_selectors)
+- [What is XSLT?](https://www.xml.com/pub/a/2000/08/holman/) introduces XSLT and XPath, including background, context, structure, concepts, and terminology - xml.com (2000)
+- [XPath tester](https://extendsclass.com/xpath-tester.html) online XPath Builder/Debugger

files/en-us/web/xpath/axes/index.md → files/en-us/web/xpath/reference/axes/index.md

@@ -1,6 +1,6 @@
 ---
 title: Axes
-slug: Web/XPath/Axes
+slug: Web/XPath/Reference/Axes
 page-type: landing-page
 sidebar: xsltsidebar
 ---

files/en-us/web/xpath/functions/boolean/index.md → files/en-us/web/xpath/reference/functions/boolean/index.md

@@ -1,6 +1,6 @@
 ---
 title: boolean
-slug: Web/XPath/Functions/boolean
+slug: Web/XPath/Reference/Functions/boolean
 page-type: xpath-function
 sidebar: xsltsidebar
 ---

files/en-us/web/xpath/functions/ceiling/index.md → files/en-us/web/xpath/reference/functions/ceiling/index.md

@@ -1,6 +1,6 @@
 ---
 title: ceiling
-slug: Web/XPath/Functions/ceiling
+slug: Web/XPath/Reference/Functions/ceiling
 page-type: xpath-function
 sidebar: xsltsidebar
 ---

files/en-us/web/xpath/functions/choose/index.md → files/en-us/web/xpath/reference/functions/choose/index.md

@@ -1,6 +1,6 @@
 ---
 title: choose
-slug: Web/XPath/Functions/choose
+slug: Web/XPath/Reference/Functions/choose
 page-type: xpath-function
 sidebar: xsltsidebar
 ---

files/en-us/web/xpath/functions/concat/index.md → files/en-us/web/xpath/reference/functions/concat/index.md

@@ -1,6 +1,6 @@
 ---
 title: concat
-slug: Web/XPath/Functions/concat
+slug: Web/XPath/Reference/Functions/concat
 page-type: xpath-function
 sidebar: xsltsidebar
 ---

files/en-us/web/xpath/functions/contains/index.md → files/en-us/web/xpath/reference/functions/contains/index.md

@@ -1,6 +1,6 @@
 ---
 title: contains
-slug: Web/XPath/Functions/contains
+slug: Web/XPath/Reference/Functions/contains
 page-type: xpath-function
 sidebar: xsltsidebar
 ---

files/en-us/web/xpath/functions/count/index.md → files/en-us/web/xpath/reference/functions/count/index.md

@@ -1,6 +1,6 @@
 ---
 title: count
-slug: Web/XPath/Functions/count
+slug: Web/XPath/Reference/Functions/count
 page-type: xpath-function
 sidebar: xsltsidebar
 ---