10up · nicholasio · May 29, 2025 · May 23, 2025
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -72,6 +72,16 @@ const config = {
 				showLastUpdateAuthor: true,
 				editUrl: 'https://github.com/10up/headstartwp/tree/trunk/docs',
 				sidebarCollapsed: false,
+				versions: {
+					current: {
+						label: 'App Router',
+						path: 'app-router',
+					},
+					'pages-router': {
+						label: 'Pages Router',
+						// path: 'pages-router',
+					},
+				},
 			},
 		],
 		[
@@ -123,6 +133,11 @@ const config = {
 						label: 'API Reference',
 						docsPluginId: 'docs',
 					},
+					{
+						type: 'docsVersionDropdown',
+						position: 'left',
+						dropdownActiveClassDisabled: true,
+					},
 				],
 			},
 			announcementBar: {

diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/...ion/01-Getting Started/headless-config.md → ...ter/01-Getting Started/headless-config.md b/...ion/01-Getting Started/headless-config.md → ...ter/01-Getting Started/headless-config.md
diff --git a/docs/versioned_docs/version-pages-router/01-Getting Started/quick-setup.md b/docs/versioned_docs/version-pages-router/01-Getting Started/quick-setup.md
@@ -0,0 +1,40 @@
+---
+sidebar_label: Quick Setup
+slug: /getting-started/quick-setup
+sidebar_position: 0
+---
+
+# Quick Setup
+
+If you're new to Next.js, we recommend reviewing [Next.js docs](https://nextjs.org/docs/getting-started).
+
+## System Requirements
+
+- Node.js 16 or later
+- NPM >= 7
+- WordPress >= 5.9 (prior versions might work but haven't been tested).
+
+## Installation
+
+The easiest way to get started with HeadstartWP is by using `create-next-app` with the official starter project.
+
+```bash
+npx create-next-app --use-npm -e https://github.com/10up/headstartwp/tree/trunk/projects/wp-nextjs
+```
+Then run `npm run dev` and open http://localhost:3000 in your browser.
+
+### Environment Variables
+
+By default, the starter project will point to `js1.10up.com`. Either change the 
+`NEXT_PUBLIC_HEADLESS_WP_URL` variable or create a `.env.local` file to override the default env variables.
+
+If you're developing locally and using HTTPS with WordPress and you don't have valid certs, you will need to add `NODE_TLS_REJECT_UNAUTHORIZED=0` as an env variable
+
+```
+NEXT_PUBLIC_HEADLESS_WP_URL=https://wordpress.test
+NODE_TLS_REJECT_UNAUTHORIZED=0
+```
+
+## Something Missing?
+
+If something is missing in the documentation or if you found some part confusing, please file an [issue](https://github.com/10up/headstartwp/issues) for the documentation repository with your suggestions for improvement.
diff --git a/...tion/01-Getting Started/quick-tutorial.md → ...uter/01-Getting Started/quick-tutorial.md b/...tion/01-Getting Started/quick-tutorial.md → ...uter/01-Getting Started/quick-tutorial.md
@@ -63,7 +63,7 @@ The `usePost` hook is one of the framework's data-fetching hooks. As its name su
 
 > Extracting the *slug* from the url **only** works when using the `[...path].js` or `[[...path]].js `catch-all route style.
 
-![SPA Data Fetching](../../static/img/spa-data-fetching-1.gif)
+![SPA Data Fetching](../../../static/img/spa-data-fetching-1.gif)
 
 Without server-side data fetching, the experience gets clunky and web vitals are greatly affected as there will be a high CLS. SEO is also affected since there is no content or SEO meta tags until the browser fetches the data.
 
@@ -160,7 +160,7 @@ Take some time to review the other routes, did you spot the pattern?
 
 As you might have noticed, the category route is not handling errors and loading states on the client. Therefore it assumes the data will always be pre-fetched on the server. If you remove `getServerSideProps`, you will see the following error.
 
-![data-error](../../static/img/error.png)
+![data-error](../../../static/img/error.png)
 
 At 10up, we strongly believe that a great developer experience increases developer productivity! Therefore the framework will try to help you, the developer, as much as it can.
 

diff --git a/...1-Getting Started/setting-up-manually.mdx → ...1-Getting Started/setting-up-manually.mdx b/...1-Getting Started/setting-up-manually.mdx → ...1-Getting Started/setting-up-manually.mdx
@@ -199,7 +199,7 @@ export default async function handler(req, res) {
 
 The framework supports ISR revalidation triggered by WordPress. To enable ISR revalidate, make sure you have the WordPress plugin enabled and activate the option in WordPress settings.
 
-![ISR Option](../../static/img/revalidate-option.png)
+![ISR Option](../../../static/img/revalidate-option.png)
 
 Then add the `revalidateHandler` to `src/pages/api/revalidate.js`
 

diff --git a/...on/01-Getting Started/wordpress-plugin.md → ...er/01-Getting Started/wordpress-plugin.md b/...on/01-Getting Started/wordpress-plugin.md → ...er/01-Getting Started/wordpress-plugin.md
@@ -39,4 +39,4 @@ Make sure to set up the path for installing this as a WordPress Plugin:
 
 Go to `Settings -> General` and scroll down until you find the "Headless Frontend URL" and enter the URL for the Headless site.
 
-![Plugin settings](../../static/img/documentation/getting-started/plugin-settings.png)
+![Plugin settings](../../../static/img/documentation/getting-started/plugin-settings.png)
diff --git a/...cumentation/02 - Data Fetching/caching.md → ...-pages-router/02-Data Fetching/caching.md b/...cumentation/02 - Data Fetching/caching.md → ...-pages-router/02-Data Fetching/caching.md
diff --git a/...tation/02 - Data Fetching/custom-hooks.md → ...s-router/02-Data Fetching/custom-hooks.md b/...tation/02 - Data Fetching/custom-hooks.md → ...s-router/02-Data Fetching/custom-hooks.md
diff --git a/...tation/02 - Data Fetching/introduction.md → ...s-router/02-Data Fetching/introduction.md b/...tation/02 - Data Fetching/introduction.md → ...s-router/02-Data Fetching/introduction.md
diff --git a/...umentation/02 - Data Fetching/mutating.md → ...pages-router/02-Data Fetching/mutating.md b/...umentation/02 - Data Fetching/mutating.md → ...pages-router/02-Data Fetching/mutating.md
diff --git a/... Data Fetching/prefetching-data-server.md → ...-Data Fetching/prefetching-data-server.md b/... Data Fetching/prefetching-data-server.md → ...-Data Fetching/prefetching-data-server.md
diff --git a/...on/02 - Data Fetching/useAuthorArchive.md → ...uter/02-Data Fetching/useAuthorArchive.md b/...on/02 - Data Fetching/useAuthorArchive.md → ...uter/02-Data Fetching/useAuthorArchive.md
diff --git a/...cumentation/02 - Data Fetching/usePost.md → ...-pages-router/02-Data Fetching/usePost.md b/...cumentation/02 - Data Fetching/usePost.md → ...-pages-router/02-Data Fetching/usePost.md
diff --git a/...tion/02 - Data Fetching/usePostOrPosts.md → ...router/02-Data Fetching/usePostOrPosts.md b/...tion/02 - Data Fetching/usePostOrPosts.md → ...router/02-Data Fetching/usePostOrPosts.md
diff --git a/...umentation/02 - Data Fetching/usePosts.md → ...pages-router/02-Data Fetching/usePosts.md b/...umentation/02 - Data Fetching/usePosts.md → ...pages-router/02-Data Fetching/usePosts.md
diff --git a/...mentation/02 - Data Fetching/useSearch.md → ...ages-router/02-Data Fetching/useSearch.md b/...mentation/02 - Data Fetching/useSearch.md → ...ages-router/02-Data Fetching/useSearch.md
diff --git a/...ion/02 - Data Fetching/useSearchNative.md → ...outer/02-Data Fetching/useSearchNative.md b/...ion/02 - Data Fetching/useSearchNative.md → ...outer/02-Data Fetching/useSearchNative.md
diff --git a/...ocumentation/02 - Data Fetching/useSeo.md → ...n-pages-router/02-Data Fetching/useSeo.md b/...ocumentation/02 - Data Fetching/useSeo.md → ...n-pages-router/02-Data Fetching/useSeo.md
diff --git a/...umentation/02 - Data Fetching/useTerms.md → ...pages-router/02-Data Fetching/useTerms.md b/...umentation/02 - Data Fetching/useTerms.md → ...pages-router/02-Data Fetching/useTerms.md
diff --git a/...cumentation/03- Utilities/sanitization.md → ...pages-router/03-Utilities/sanitization.md b/...cumentation/03- Utilities/sanitization.md → ...pages-router/03-Utilities/sanitization.md
diff --git a/...nberg/rendering-blocks-in-react-native.md → ...nberg/rendering-blocks-in-react-native.md b/...nberg/rendering-blocks-in-react-native.md → ...nberg/rendering-blocks-in-react-native.md
@@ -213,4 +213,4 @@ const RNImageBlock = ({ domNode, height, width, src }) => {
 
 The demo app should render something like this
 
-![Blocks App](../../static/img/blocks-app.png)
+![Blocks App](../../../static/img/blocks-app.png)
diff --git a/...entation/05-Gutenberg/rendering-blocks.md → ...s-router/05-Gutenberg/rendering-blocks.md b/...entation/05-Gutenberg/rendering-blocks.md → ...s-router/05-Gutenberg/rendering-blocks.md
@@ -133,6 +133,6 @@ import {
 ```
 
 You should see something like this
-![Debug Blocks](../../static/img/debug-blocks.png)
+![Debug Blocks](../../../static/img/debug-blocks.png)
 
 By inspecting the props you can see you have access to things like block name, className, and even the Gutenberg attributes. You could, in theory, build your implementation for every block without loading any of the default Gutenberg styles, shipping your own component library/design system.
diff --git a/...n/05-Gutenberg/rendering-custom-blocks.md → ...r/05-Gutenberg/rendering-custom-blocks.md b/...n/05-Gutenberg/rendering-custom-blocks.md → ...r/05-Gutenberg/rendering-custom-blocks.md
diff --git a/...on/06-WordPress Integration/basic-auth.md → ...er/06-WordPress Integration/basic-auth.md b/...on/06-WordPress Integration/basic-auth.md → ...er/06-WordPress Integration/basic-auth.md
diff --git a/...ntation/06-WordPress Integration/feeds.md → ...-router/06-WordPress Integration/feeds.md b/...ntation/06-WordPress Integration/feeds.md → ...-router/06-WordPress Integration/feeds.md
diff --git a/...ion/06-WordPress Integration/gutenberg.md → ...ter/06-WordPress Integration/gutenberg.md b/...ion/06-WordPress Integration/gutenberg.md → ...ter/06-WordPress Integration/gutenberg.md
diff --git a/...ion/06-WordPress Integration/multisite.md → ...ter/06-WordPress Integration/multisite.md b/...ion/06-WordPress Integration/multisite.md → ...ter/06-WordPress Integration/multisite.md
@@ -84,7 +84,7 @@ When using locales make sure to add the locale to `Settings -> General -> Headle
 
 As an example, the first site config in the example above would need the following settings in WordPress.
 
-![Plugin settings Multisite Locale](../../static/img/documentation/wordpress-integration/multisite-locale.png)
+![Plugin settings Multisite Locale](../../../static/img/documentation/wordpress-integration/multisite-locale.png)
 
 
 ### Middleware

diff --git a/...tion/06-WordPress Integration/polylang.md → ...uter/06-WordPress Integration/polylang.md b/...tion/06-WordPress Integration/polylang.md → ...uter/06-WordPress Integration/polylang.md
diff --git a/...tion/06-WordPress Integration/previews.md → ...uter/06-WordPress Integration/previews.md b/...tion/06-WordPress Integration/previews.md → ...uter/06-WordPress Integration/previews.md
diff --git a/...on/06-WordPress Integration/revalidate.md → ...er/06-WordPress Integration/revalidate.md b/...on/06-WordPress Integration/revalidate.md → ...er/06-WordPress Integration/revalidate.md
@@ -18,7 +18,7 @@ HeadstartWP supports Next.js ISR via the WordPress plugin and via `@10up/next-re
 ### Plugin setup
 
 HeadstartWP supports On-Demand Revalidation and it requires installing the WordPress Plugin. On-Demand Revalidation is opt-in and must be manually enabled in the plugin's settings (Settings -> General).
-![Plugin settings](../../static/img/documentation/getting-started/plugin-settings.png)
+![Plugin settings](../../../static/img/documentation/getting-started/plugin-settings.png)
 
 The plugin expects the revalidate endpoint to live at  `/api/revalidate`. It is possible to customize this endpoint via the `tenup_headless_isr_revalidate_endpoint`.
 
@@ -79,7 +79,7 @@ If you are hosting on Vercel you do not need this package.
 
 Our solution to this problem has been to replace the filesystem cache with a redis cache provider. So whenever Next.js revalidates a page instead of storing the static page in disk, it will write to a shared redis instance that all of the containers would be talking to. The diagram below exemplifies how it works.
 
-![Plugin settings](../../static/img/documentation/wordpress-integration/next-redis-cache-provider.png)
+![Plugin settings](../../../static/img/documentation/wordpress-integration/next-redis-cache-provider.png)
 
 To set up `@10up/next-redis-cache-provider` first install it via npm:
 

diff --git a/docs/documentation/08-Guides/ab-test-link.md → ...on-pages-router/08-Guides/ab-test-link.md b/docs/documentation/08-Guides/ab-test-link.md → ...on-pages-router/08-Guides/ab-test-link.md
@@ -103,9 +103,9 @@ Note that the link is converted to a relative link to remove the WordPress domai
 
 To test this, open a page. Then, check which bucket you’re in
 
-![AB Test bucket](../../static/img/a-b-test-1.png)
+![AB Test bucket](../../../static/img/a-b-test-1.png)
 
 In the example above, I was assigned the “mpa” bucket I should see a full page reload when navigating to internal links inside the post content. You can change to the “spa” bucket by modifying the cookie.
 
 
-![AB Test Link](../../static/img/a-b-testing-link.gif)
+![AB Test Link](../../../static/img/a-b-testing-link.gif)
diff --git a/docs/documentation/08-Guides/linaria.md → ...version-pages-router/08-Guides/linaria.md b/docs/documentation/08-Guides/linaria.md → ...version-pages-router/08-Guides/linaria.md
diff --git a/docs/documentation/08-Guides/typescript.md → ...sion-pages-router/08-Guides/typescript.md b/docs/documentation/08-Guides/typescript.md → ...sion-pages-router/08-Guides/typescript.md
diff --git a/...documentation/08-Guides/youtube-facade.md → ...-pages-router/08-Guides/youtube-facade.md b/...documentation/08-Guides/youtube-facade.md → ...-pages-router/08-Guides/youtube-facade.md
diff --git a/docs/versioned_docs/version-pages-router/index.md b/docs/versioned_docs/version-pages-router/index.md
@@ -0,0 +1,8 @@
+---
+sidebar_position: 0
+sidebar_label: Introduction
+---
+
+# Introduction
+
+Welcome to HeadstartWP documentation site! If you are new, we highly recommend reading all the way through [Getting Started](/learn/getting-started/quick-setup/) first.
diff --git a/docs/versioned_sidebars/version-pages-router-sidebars.json b/docs/versioned_sidebars/version-pages-router-sidebars.json
@@ -0,0 +1,8 @@
+{
+  "tutorialSidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}
diff --git a/docs/versions.json b/docs/versions.json
@@ -0,0 +1 @@
+["pages-router"]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -39,4 +39,4 @@ Make sure to set up the path for installing this as a WordPress Plugin:

		Go to `Settings -> General` and scroll down until you find the "Headless Frontend URL" and enter the URL for the Headless site.

		![Plugin settings](../../static/img/documentation/getting-started/plugin-settings.png)
		![Plugin settings](../../../static/img/documentation/getting-started/plugin-settings.png)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -213,4 +213,4 @@ const RNImageBlock = ({ domNode, height, width, src }) => {

		The demo app should render something like this

		![Blocks App](../../static/img/blocks-app.png)
		![Blocks App](../../../static/img/blocks-app.png)