routerino 2.3.4 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Routerino
 
-> A lightweight, SEO-optimized React router for modern websites and applications
+> A lightweight, SEO-optimized React router & SSG for modern websites and applications
 
 For teams who want SPA simplicity with search-friendly static HTML, Open Graph previews, and **no framework lock-in.**
 
@@ -91,6 +91,7 @@ This simple configuration automatically handles routing, meta tags, and SEO opti
 - Enhanced User Experience
   - Support for sharing and social preview metadata
   - Snappy page transitions with automatic scroll reset, eliminating the jarring experience of landing mid-page when navigating
+  - Hash link support: SPA navigation to `/page#section` correctly scrolls to the target element, mimicking native browser behavior
 
 ## Installation
 
@@ -128,7 +129,18 @@ export const routes = [
 />;
 ```
 
-Links are just standard HTML anchor tags. No need to use special `<Link>` components—you can use whatever components or design system you like. For example: <a href="/some-page/">a link</a> is perfectly valid. This is very handy for markdown-based content. With standard link support in Routerino, you won't need to [transform your markdown content with custom React components](https://github.com/remarkjs/react-markdown?tab=readme-ov-file#appendix-b-components). Routerino handles same-origin anchor clicks. Cross-origin links and non-HTTP schemes (e.g., mailto:, tel:) are handled by the browser as usual.
+Links are just standard HTML anchor tags. No need to use special `<Link>` components—you can use whatever components or design system you like. For example: <a href="/some-page/">a link</a> is perfectly valid. This is very handy for markdown-based content. With standard link support in Routerino, you won't need to [transform your markdown content with custom React components](https://github.com/remarkjs/react-markdown?tab=readme-ov-file#appendix-b-components).
+
+Routerino handles same-origin anchor clicks via SPA navigation. The browser handles the rest natively, including:
+
+- **Cross-origin links** (different domain)
+- **Non-HTTP schemes** (mailto:, tel:, javascript:, etc.)
+- **Modified clicks** (Ctrl/Cmd+click, Shift+click, Alt+click, right-click)
+- **`target="_blank"`** links
+- **`download`** attribute links
+- **`rel="external"`** links
+- **File extension links** — PDFs, ZIPs, images, fonts, videos, JSON, XML, and 50+ other file types are recognized automatically
+- **Custom patterns** — use the [`ignorePatterns`](#ignorepatterns-string) prop for additional exclusions (e.g., `/api/`, `/legacy/`)
 
 ### Programmatic Navigation
 
@@ -223,6 +235,7 @@ All of these are optional, so it's easy to get started with nothing but a bare-b
 | [imageUrl](#imageurl-string)                   | string          | Default image URL for sharing     | `null`                        |
 | [touchIconUrl](#touchiconurl-string)           | string          | Image URL for PWA homescreen icon | `null`                        |
 | [debug](#debug-boolean)                        | boolean         | Enable debug mode                 | `false`                       |
+| [ignorePatterns](#ignorepatterns-string)       | string[]        | URL patterns to skip SPA routing  | `[]`                          |
 
 ##### `title`: string;
 
@@ -299,7 +312,9 @@ Default: `false`
 
 ##### `baseUrl`: string;
 
-The base URL to use for canonical tags and og:url meta tags. If not provided, uses `window.location.origin`. This is useful when you want to specify the production URL regardless of the current environment.
+The base URL to use for canonical tags and og:url meta tags. If not provided, uses `window.location.origin`.
+
+This is useful when your site is accessible from multiple domains (for example, both example.com and example.net point to the same app). Set it to the preferred domain and all canonical and og:url tags will consistently point there. Also helpful for pinning to the production URL in development or staging environments.
 
 **Important:** The baseUrl must NOT end with a trailing slash (`/`). Correct example: `"https://example.com"`
 
@@ -337,6 +352,21 @@ Example debug output:
 
 Default: `false`
 
+##### `ignorePatterns`: string[];
+
+An array of regex pattern strings to match against link hrefs. Any same-origin link matching one of these patterns will **not** be intercepted by the SPA router — the browser will handle the navigation natively instead.
+
+Patterns are tested case-insensitively against the full resolved href (including origin).
+
+```jsx
+// Skip API endpoints and a legacy section
+<Routerino routes={routes} ignorePatterns={["/api/", "/admin/legacy/"]} />
+```
+
+Routerino also has a built-in list of file extensions that are automatically skipped: `.pdf`, `.zip`, `.docx`, `.png`, `.jpg`, `.svg`, `.mp4`, `.json`, `.xml`, `.csv`, `.txt`, `.ico`, `.woff2`, `.woff`, `.ttf`, `.mp3`, `.wav`, `.epub`, `.map`, `.css`, `.js`, `.wasm`, and many more. The `ignorePatterns` prop is for additional custom patterns beyond these defaults.
+
+Default: `[]`
+
 #### RouteConfig props
 
 There is a default RouteConfig that will be loaded if you don't specify any routes. The default route is a basic template that can confirm your app is working and routing is good to go.
@@ -401,6 +431,31 @@ An array of HeadTag objects that can be added to the route to manage meta tags,
 
 - `target` (string): The "target" attribute of the tag. Defines where to open the linked resource.
 
+- `innerHTML` (string): Inner HTML content for tags that require a closing tag, such as `<script>` and `<style>`. When provided, the tag is rendered as `<tag attrs>innerHTML</tag>` instead of a self-closing element. This enables structured data (JSON-LD), inline CSS, and other tag-body content.
+
+##### Structured Data Example
+
+```jsx
+{
+  path: "/about/",
+  element: <AboutPage />,
+  tags: [{
+    tag: "script",
+    type: "application/ld+json",
+    innerHTML: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
+        { "@type": "ListItem", "position": 2, "name": "About", "item": "https://example.com/about/" },
+      ],
+    }),
+  }],
+}
+```
+
+This works both at runtime (via `updateHeadTag`) and during static site generation (via the forge plugin).
+
 ### Using the `useRouterino` Hook
 
 The `useRouterino` hook provides access to router state from any child component. This is the primary way to access route information and update head tags dynamically.
@@ -716,6 +771,8 @@ With Prerender (SPA):
 
 You can override the default with `useTrailingSlash={false}` if you prefer URLs without trailing slashes. Either way, Routerino ensures search engines see consistent, canonical URLs.
 
+**Multi-domain deployments**: If your site is served from multiple domains, set `baseUrl` to the preferred domain to keep all canonical and og:url tags pointing to one place. For example, `<Routerino baseUrl="https://example.com" routes={routes} />` ensures search engines see one canonical domain even when the same page is reachable at example.net.
+
 ### Sitemap Generation
 
 - Automate the creation of `sitemap.xml` and `robots.txt` during your build process with Routerino Forge.
@@ -807,11 +864,25 @@ This creates an engaging Twitter preview with a large image, title, and descript
 ### Additional SEO Considerations
 
 - Use semantic HTML elements in your components for better content structure.
-- Implement structured data (JSON-LD) where applicable to enhance rich snippets in search results.
+- Implement structured data (JSON-LD) where applicable to enhance rich snippets in search results. Use the `innerHTML` property on a `<script type="application/ld+json">` head tag (see the [Structured Data Example](#structured-data-example) above).
 - Ensure your site is mobile-friendly and loads quickly for better search engine rankings.
 
 By following these practices, you'll improve your site's SEO performance and social media presence when using Routerino.
 
+### Hash Links
+
+Routerino supports standard `<a href="/page#section">` links for SPA navigation. After React renders the new page, it finds the element with the matching `id` and scrolls it into view.
+
+**Sticky headers**: If your site has a fixed header, use the CSS [`scroll-margin-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top) property to offset the scroll target so content isn't hidden behind the header:
+
+```css
+[id] {
+  scroll-margin-top: 80px; /* match your header height */
+}
+```
+
+This works for SPA navigation, native browser hash navigation, and direct page loads — no extra props or router changes needed.
+
 ## Sitemap and robots.txt Generation
 
 When using Routerino Forge for static site generation, `sitemap.xml` and `robots.txt` files are automatically generated during the build process:
@@ -915,11 +986,11 @@ routerinoForge({
 - Smart sizing: Uses aspect-ratio only to prevent layout shift without forcing dimensions
 - Hides images initially with `opacity: 0` to prevent broken image icons during load
 
-**Note:** Image optimization requires `ffmpeg` to be installed. Without it, images work normally but without blur placeholders. Install with `brew install ffmpeg` (Mac), `apt install ffmpeg` (Ubuntu), or `choco install ffmpeg` (Windows).
+**Note:** Image optimization requires `ffmpeg` to be installed on your system. Install with `brew install ffmpeg` (Mac), `apt install ffmpeg` (Debian/Ubuntu), or `choco install ffmpeg` (Windows). Without ffmpeg, the Image component still works but falls back to the original image without optimization. A warning is shown during build if ffmpeg is not found but Image components are used.
 
 ##### CI/CD Setup for Image Optimization
 
-To enable image optimization in your CI/CD pipeline, you need to install ffmpeg. Here are examples for the most common setups:
+For CI/CD environments without ffmpeg pre-installed, you'll need to install it as part of your build process. Here are examples:
 
 ###### GitHub Actions