fix: footnote styles, backlink jump (#2104)

Co-authored-by: Dimitri POSTOLOV <en3m@ya.ru>
Co-authored-by: Dimitri POSTOLOV <dmytropostolov@gmail.com>

.changeset/gorgeous-tips-cough.md

@@ -0,0 +1,6 @@
+---
+"nextra-theme-docs": patch
+"nextra-theme-blog": patch
+---
+
+fix footnotes and backlink jump

docs/package.json

@@ -22,9 +22,9 @@
     "@svgr/webpack": "^8.0.1",
     "@types/node": "^18.11.18",
     "@types/react": "^18.0.26",
-    "autoprefixer": "^10.4.14",
+    "autoprefixer": "^10.4.15",
     "eslint": "^8.30.0",
-    "postcss": "^8.4.21",
-    "tailwindcss": "^3.3.2"
+    "postcss": "^8.4.28",
+    "tailwindcss": "^3.3.3"
   }
 }

examples/blog/package.json

@@ -1,22 +1,20 @@
 {
   "name": "example-blog",
+  "type": "module",
   "license": "MIT",
   "private": true,
-  "main": "index.js",
   "scripts": {
     "build": "next build",
     "clean": "rimraf .next .turbo",
-    "debug": "NODE_OPTIONS='--inspect' next dev",
     "dev": "next",
-    "start": "next start",
-    "vercel-build": "yarn workspace nextra run build && yarn workspace nextra-theme-docs run build && yarn build"
+    "start": "next start"
   },
   "dependencies": {
     "next": "^13.4.8",
     "nextra": "workspace:*",
     "nextra-theme-blog": "workspace:*",
-    "react": "*",
-    "react-dom": "*"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "dependenciesMeta": {
     "nextra": {

examples/blog/pages/posts/callout.mdx

@@ -29,13 +29,13 @@ import { CopyIcon, GitHubIcon, MenuIcon } from 'nextra/icons'
 
 ### Info
 
-<Callout type="info">This is an info callout.</Callout>
+<Callout type="info">This is an info callout. [^2]</Callout>
 
 ### Warning
 
 <Callout type="warning">This is a warning callout.</Callout>
 
-### With custom emoji
+### With custom emoji [^1]
 
 <Callout emoji="🚀">This is a callout with a custom emoji.</Callout>
 
@@ -103,3 +103,6 @@ Contents for step 2.
   <Card icon={<GitHubIcon />} title="Tabs" href="/bar" />
   <Card icon={<MenuIcon />} title="Steps" href="/baz" />
 </Cards>
+
+[^1]: With custom emoji
+[^2]: This is an info callout.

examples/docs/package.json

@@ -2,14 +2,11 @@
   "name": "example-docs",
   "license": "MIT",
   "private": true,
-  "main": "index.js",
   "scripts": {
     "build": "next build",
     "clean": "rimraf .next .turbo",
-    "debug": "NODE_OPTIONS='--inspect' next dev",
     "dev": "next",
-    "start": "next start",
-    "vercel-build": "yarn workspace nextra run build && yarn workspace nextra-theme-docs run build && yarn build"
+    "start": "next start"
   },
   "dependencies": {
     "next": "^13.4.8",

examples/docs/src/pages/get-started.mdx

@@ -1,3 +1,5 @@
+import { Callout, Steps } from 'nextra/components';
+
 # Get Started
 
 ## Quick Start with Vercel
@@ -11,51 +13,22 @@ Once done, every change in the repository will be deployed automatically.
 
 ## Create Manually
 
-Nextra works like a Next.js plugin, and it accepts a theme config (layout) to render the page. To start:
-
-1. Install Next.js, Nextra and React
-
-import { Callout, Tabs, Tab } from 'nextra/components';
-
-<Tabs items={['npm', 'yarn', 'pnpm']} defaultIndex={1}>
-  <Tab>
-    ```bash
-    npm i react react-dom next nextra
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    yarn add react react-dom next nextra
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    pnpm i react react-dom next nextra
-    ```
-  </Tab>
-</Tabs>
-
-2. Install the docs theme
-
-<Tabs items={['npm', 'yarn', 'pnpm']} defaultIndex={1}>
-  <Tab>
-    ```bash
-    npm i nextra-theme-docs
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    yarn add nextra-theme-docs
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    pnpm i nextra-theme-docs
-    ```
-  </Tab>
-</Tabs>
-
-3. Create the following Next.js config and theme config under the root directory:
+Nextra works like a Next.js plugin, and it accepts a theme config (layout) to render the page. To start: [^3]
+
+<Steps>
+### Install Next.js, Nextra and React [^1]
+
+```sh npm2yarn
+npm i react react-dom next nextra
+```
+
+### Install the docs theme [^2]
+
+```sh npm2yarn
+npm i nextra-theme-docs
+```
+
+### Create the following Next.js config and theme config under the root directory
 
 ```js filename="next.config.js"
 const withNextra = require('nextra')({
@@ -66,7 +39,7 @@ const withNextra = require('nextra')({
 module.exports = withNextra()
 ```
 
-4. Create a `theme.config.js` file for the docs theme:
+### Create a `theme.config.js` file for the docs theme
 
 ```js filename="theme.config.js"
 /**
@@ -111,7 +84,9 @@ export default {
   [here](/themes/docs/configuration).
 </Callout>
 
-5. You are good to go! Run `yarn next` to start.
+### You are good to go! Run `next dev` to start
+
+</Steps>
 
 ---
 
@@ -126,3 +101,7 @@ export default {
 <Callout>
 You can also use [`<style jsx>`](https://nextjs.org/docs/basic-features/built-in-css-support#css-in-js) to style elements inside `theme.config.js`.
 </Callout>
+
+[^1]: Install Next.js, Nextra and React.
+[^2]: Install the docs theme.
+[^3]: To start.

examples/swr-site/package.json

@@ -19,8 +19,8 @@
     "next": "^13.4.8",
     "nextra": "workspace:*",
     "nextra-theme-docs": "workspace:*",
-    "react": "*",
-    "react-dom": "*",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
     "react-intersection-observer": "^8.26.2"
   },
   "dependenciesMeta": {
@@ -32,9 +32,9 @@
     }
   },
   "devDependencies": {
-    "autoprefixer": "*",
-    "postcss": "*",
-    "tailwindcss": "*"
+    "autoprefixer": "^10.4.15",
+    "postcss": "^8.4.28",
+    "tailwindcss": "^3.3.3"
   },
   "nextBundleAnalysis": {
     "budget": 358400,

package.json

@@ -52,8 +52,7 @@
       "next-themes": "^0.2.1",
       "next": "^13.4.8",
       "@types/react": "^18.0.15",
-      "@types/react-dom": "^18.0.6",
-      "postcss": "^8.4.21"
+      "@types/react-dom": "^18.0.6"
     },
     "patchedDependencies": {
       "@changesets/assemble-release-plan@5.2.4": "patches/@changesets__assemble-release-plan@5.2.4.patch"

packages/nextra-theme-blog/package.json

@@ -71,14 +71,14 @@
     "concurrently": "^8.0.0",
     "next": "^13.4.8",
     "nextra": "workspace:*",
-    "postcss": "^8.4.21",
+    "postcss": "^8.4.28",
     "postcss-cli": "^10.1.0",
     "postcss-import": "^15.1.0",
     "postcss-lightningcss": "^0.9.0",
     "react": "^18.2.0",
     "react-cusdis": "^2.1.3",
     "react-dom": "^18.2.0",
-    "tailwindcss": "^3.3.2",
+    "tailwindcss": "^3.3.3",
     "vitest": "^0.34.0"
   },
   "sideEffects": false

packages/nextra-theme-blog/src/mdx-theme.tsx

@@ -33,37 +33,46 @@ function HeadingLink({
   tag: Tag,
   children,
   id,
+  className,
   ...props
 }: ComponentProps<'h2'> & { tag: `h${2 | 3 | 4 | 5 | 6}` }): ReactElement {
   return (
-    <Tag className={`subheading-${Tag}`} {...props}>
+    <Tag
+      className={
+        // can be added by footnotes
+        className === 'sr-only'
+          ? 'nx-sr-only'
+          : `nx-not-prose subheading-${Tag}`
+      }
+      {...props}
+    >
       {children}
-      <span className="nx-absolute -nx-mt-7" id={id} />
       <a
         href={id && `#${id}`}
+        id={id}
         className="subheading-anchor"
         aria-label="Permalink for this section"
       />
     </Tag>
   )
 }
 
-const A = ({ children, ...props }: ComponentProps<'a'>) => {
-  const isExternal =
-    props.href?.startsWith('https://') || props.href?.startsWith('http://')
-  if (isExternal) {
+const EXTERNAL_HREF_REGEX = /https?:\/\//
+
+const A = ({ children, href = '', ...props }: ComponentProps<'a'>) => {
+  if (EXTERNAL_HREF_REGEX.test(href)) {
     return (
-      <a target="_blank" rel="noreferrer" {...props}>
+      <a href={href} target="_blank" rel="noreferrer" {...props}>
         {children}
         <span className="nx-sr-only nx-select-none"> (opens in a new tab)</span>
       </a>
     )
   }
-  return props.href ? (
-    <Link href={props.href} passHref legacyBehavior>
+  return (
+    <Link href={href} passHref legacyBehavior>
       <a {...props}>{children}</a>
     </Link>
-  ) : null
+  )
 }
 
 const useComponents = (): Components => {

packages/nextra-theme-blog/src/styles.css

@@ -8,6 +8,10 @@
 @import 'nextra/styles/steps.css';
 @import 'nextra/styles/cards.css';
 
+html {
+  @apply nx-scroll-pt-5;
+}
+
 body {
   @apply nx-px-4;
 }
@@ -37,3 +41,7 @@ h1 {
 .nx-prose .nextra-callout p {
   @apply nx-m-0;
 }
+
+.footnotes a[data-footnote-backref] {
+  font-family: initial;
+}

packages/nextra-theme-docs/css/styles.css

@@ -11,7 +11,7 @@
 @import './typesetting-article.css';
 
 html {
-  @apply nx-antialiased nx-text-base;
+  @apply nx-antialiased nx-text-base nx-scroll-pt-[--nextra-navbar-height];
   font-feature-settings:
     'rlig' 1,
     'calt' 1,
@@ -154,6 +154,10 @@ input[type='search'] {
   }
 }
 
+.footnotes a[data-footnote-backref] {
+  font-family: initial;
+}
+
 @keyframes nextra-fadein {
   0% {
     opacity: 0;

packages/nextra-theme-docs/package.json

@@ -63,13 +63,13 @@
     "jsdom": "^22.0.0",
     "next": "^13.4.8",
     "nextra": "workspace:*",
-    "postcss": "^8.4.21",
+    "postcss": "^8.4.28",
     "postcss-cli": "^10.1.0",
     "postcss-import": "^15.1.0",
     "postcss-lightningcss": "^0.9.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "tailwindcss": "^3.3.2",
+    "tailwindcss": "^3.3.3",
     "vitest": "^0.34.0"
   },
   "sideEffects": [