Merge pull request #195 from swup/feat/updates

Update docs on newer features
swup · Jul 19, 2024 · e403825 · e403825
2 parents 71053b9 + 42c78c7
commit e403825
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 11 deletions.
diff --git a/src/docs/api/markup.md b/src/docs/api/markup.md
@@ -15,21 +15,24 @@ Control swup's behavior using specific DOM attributes on links and other element
 
 ## Ignore links
 
-Swup can be disabled on a per-link basis by annotating a link or any of its
-ancestors with `data-no-swup`:
+Swup can be disabled on a per-link basis by annotating a link with `data-no-swup`.
 
 ```html
 <a href="/" data-no-swup>Ignored</a>
+```
+
+Add the attribute to a common container to ignore all links within.
 
-<nav data-no-swup>
+```html
+<section data-no-swup>
   <a href="/">Ignored</a>
-</nav>
+  <a href="/">Ignored</a>
+</section>
 ```
 
 ## Set a custom animation
 
-Adding a `data-swup-animation` attribute on a link will change the animation for a
-specific visit.
+Set a custom animation for a specific link by adding a `data-swup-animation` attribute.
 
 ```html
 <a href="/" data-swup-animation="slide">
@@ -51,6 +54,17 @@ html.is-changing.to-slide .transition-page {
 }
 ```
 
+Add the attribute to a common container to set an animation for all links within. Animations defined
+on a link take precedence over animations defined on a parent.
+
+```html
+<section data-swup-animation="slide">
+  <a href="/">Slide</a>
+  <a href="/">Slide</a>
+  <a href="/" data-swup-animation="fade">Fade</a>
+</section>
+```
+
 ## Persist element state
 
 Some elements need to keep their state between page loads, e.g. autoplaying videos, animations or
@@ -74,3 +88,14 @@ adding a `data-swup-history` attribute with the value `replace` to a link:
 ```html
 <a href="/" data-swup-history="replace">
 ```
+
+Add the attribute to a common container to set history mode for all links within. Settings defined
+on a link take precedence over settings defined on a parent.
+
+```html
+<section data-swup-history="replace">
+  <a href="/">Replace</a>
+  <a href="/">Replace</a>
+  <a href="/" data-swup-history="push">Push</a>
+</section>
+```
diff --git a/src/docs/api/properties.md b/src/docs/api/properties.md
@@ -21,6 +21,22 @@ Current [options](/options/), after merging swup defaults and user options.
 
 Array of all [plugin](/plugins/) instances currently enabled on swup.
 
+## location
+
+The location of the page last navigated to, after any redirects. This object inherits all properties
+from a native [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object, with an additional
+`url` property that combines path and query param.
+
+```js
+swup.location.href     // https://example.net/path?query#hash
+swup.location.url      // /path?query
+swup.location.pathname // /path
+swup.location.search   // ?query
+swup.location.hash     // #hash
+```
+
 ## currentPageUrl
 
 The URL of the page last navigated to, after any redirects.
+
+> [!NOTE] This property is deprecated, use `swup.location.url` instead.
diff --git a/src/docs/lifecycle/visit.md b/src/docs/lifecycle/visit.md
@@ -33,16 +33,20 @@ This is an example visit object for a navigation from `/home` to `/about#anchor`
 
 ```javascript
 {
+  id: 1042739, /* A unique ID to identify this visit */
   from: {
-    url: '/home'
+    url: '/home',
+    hash: ''
   },
   to: {
     url: '/about',
     hash: '#anchor',
     html: undefined, /* The HTML string of /about, when it's loaded */,
     document: undefined /* The parsed document of /about, when it's loaded */,
   },
-  containers: ['#swup'],
+  containers: [
+    '#swup'
+  ],
   animation: {
     animate: true,
     name: 'fade'
@@ -173,11 +177,12 @@ swup.hooks.on('visit:start', (visit) => {
 
 ### Do something with the incoming document
 
-As soon as the next page is loaded, you can access the `document` of that page and do something with it. For example, you could make sure the `lang` tag is being updated on your `<html>` element:
+As soon as the next page is loaded, you can access the `document` of that page and do something with
+it. For example, you could make sure the `lang` attribute is updated on your `<html>` element:
 
 ```javascript
 swup.hooks.on('content:replace', (visit) => {
-  const langAttr = visit.to.document?.documentElement.getAttribute('lang');
-  if (langAttr) document.documentElement.setAttribute('lang', langAttr);
+  const lang = visit.to.document?.documentElement.getAttribute('lang');
+  if (lang) document.documentElement.setAttribute('lang', lang);
 });
 ```