chore(ia): reorg /web/xpath

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

@@ -188,7 +188,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,19 @@
+---
+title: Comparison of CSS selectors and XPath
+short-title: 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,17 @@
+---
+title: XPath guides
+short-title: Guides
+slug: Web/XPath/Guides
+page-type: landing-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,11 +1,12 @@
 ---
 title: Introduction to using XPath in JavaScript
-slug: Web/XPath/Introduction_to_using_XPath_in_JavaScript
+short-title: Using XPath in JavaScript
+slug: Web/XPath/Guides/Introduction_to_using_XPath_in_JavaScript
 page-type: guide
+sidebar:
+  - xsltsidebar
 ---
 
-{{XsltSidebar}}
-
 This document describes the interface for using [XPath](/en-US/docs/Web/XPath) in JavaScript.
 The main interface to using XPath is the [evaluate](/en-US/docs/Web/API/Document/evaluate) function of the [document](/en-US/docs/Web/API/Document) object.
 
@@ -81,7 +82,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(
@@ -324,11 +325,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,11 +1,11 @@
 ---
 title: XPath snippets
-slug: Web/XPath/Snippets
+slug: Web/XPath/Guides/Snippets
 page-type: guide
+sidebar:
+  - xsltsidebar
 ---
 
-{{XsltSidebar}}
-
 This article provides some XPath code snippets — simple examples of how to a few simple **utility functions** based on standard interfaces from the [DOM Level 3 XPath specification](https://www.w3.org/TR/DOM-Level-3-XPath/) that expose XPath functionality to JavaScript code. The snippets are functions you can use in the real world in your own code.
 
 ### Node-specific evaluator function
@@ -153,4 +153,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)