update MDX documentation for clarity and fix broken links

Author: chrisweb

app/web_development/tutorials/next-js-static-first-mdx-starterkit/code-highlighting-plugin/page.mdx

@@ -55,7 +55,7 @@ For me, the best about **rehype pretty code** is that it uses [shiki](https://sh
 
 If you use Typescript for your Next.js 15 config file and import this plugin, then you will get a node.js error telling you that it can NOT import the "vscode-textmate" package (which is a shiki dependency, shiki is used by this plugin).
 
-As described on a previous page, the reason for this is that next.config.ts files have [NO support for ESM only packages](/web_development/tutorials/next-js-static-first-mdx-starterkit/next-config#nextconfigts-does-not-yet-support-esm) (yet)
+As described on a previous page, the reason for this is that next.config.ts files have [NO support for ESM only packages](/web_development/tutorials/next-js-static-first-mdx-starterkit/next-config#nextconfigts-does-not-support-esm-only-packages) (yet)
 
 As of now the only workaround for this problem (besides not using this plugin, as there are many alternatives like [rehype-starry-night](https://github.com/rehypejs/rehype-starry-night) and [rehype-highlight)](https://github.com/rehypejs/rehype-highlight)), is to go back to using a **next.config.mjs** file. You could rename your current next.config.ts to _next.config.ts (with an underscore) to have a backup and then make a copy that you name it next.config.mjs. Then you need to edit the next.config.mjs to comment out type imports and comment out code that creates or uses types. After that all you can do is keep using a Javascript file until the Typescript configuration files get support for ESM only packages
 

app/web_development/tutorials/next-js-static-first-mdx-starterkit/introduction/page.mdx

@@ -117,9 +117,9 @@ Or yet another solution is to use the [versionlens for VSCode extension](https:/
 
 There are a few features that I could NOT use in this tutorial or had to disable and I wanted you to be aware of it before we start with the actual tutorial
 
-* Converting the **next.config.js** file to a next.config.ts file: as I describe in the upcoming "Next.js 15 config" page there is [NO support for ESM only packages](/web_development/tutorials/next-js-static-first-mdx-starterkit/next-config#nextconfigts-does-not-yet-support-esm) (but it is coming)
+* Converting the **next.config.js** file to a next.config.ts file: as I describe in the upcoming "Next.js 15 config" page there is [NO support for ESM only packages](/web_development/tutorials/next-js-static-first-mdx-starterkit/next-config#nextconfigts-does-not-support-esm-only-packages) (but it is coming)
 * Using **Turbopack** in development: as we will see in a future chapter does NOT always work (don't get me wrong, I love Turbopack and plan on using it fully as soon as possible, but I also feel like we need to give Turbopack a bit more time to mature), one such case where Turbopack will fail is when [you also intend to enable typed routes](/web_development/tutorials/next-js-static-first-mdx-starterkit/typescript-plugin-and-typed-routes#turbopack-in-nextjs-15-does-not-yet-support-typed-routes), we will see another case when we start working on logging errors, we will use the Sentry SDK for Next.js, which works only without Turbopack as the [Sentry SDK is NOT compatible with Turbopack](/web_development/tutorials/next-js-static-first-mdx-starterkit/error-handling-and-logging#sentry-does-not-yet-support-turbopack) (just yet), then in Next.js v15.0 Turbopack has NO support for MDX (remark / rehype) plugins, in Next.js v15.1 they just added a new **experimental** loader 🎉 that allows you to use MDX plugins written in Javascript with Turbopack (which is written in Rust), more about this in the upcoming [MDX plugins page](/web_development/tutorials/next-js-static-first-mdx-starterkit/mdx-plugins#turbopack-support-for-mdx-remark--rehype-plugins)
-* Support for ESLint **flat config** files: Next.js 15 supports ESLint flat config files, meaning you can create a flat config and Next.js will recognize it, but [Next.js packages are NOT using flat configs](/web_development/tutorials/next-js-static-first-mdx-starterkit/linting-setup-using-eslint#not-everything-is-eslint-v9-and-flat-config-optional). But we are getting there, ~~CNA v15.0 for example still installs ESLint v8~~ this is fixed if you use CNA version >= 15.1 (CNA 15.1 now installs ESLint v9), so now everything is ESLint v9 compatible. Both Next.js ESLint packages (the config and the plugin) still use classic configuration files (RC) and NOT flat config, which means you need to use the FlatCompat mode if you want to use them "as is" in your flat config
+* Support for ESLint **flat config** files: Next.js 15 supports ESLint flat config files, meaning you can create a flat config and Next.js will recognize it, but [Next.js packages are NOT using flat configs](/web_development/tutorials/next-js-static-first-mdx-starterkit/linting-setup-using-eslint#nextjs-15-needs-eslint-compatibility-mode-optional), which means you have to use the ESLint compatibility mode. But we are getting there, ~~CNA v15.0 for example still installs ESLint v8~~ this is fixed if you use CNA version >= 15.1 (CNA 15.1 now installs ESLint v9), so now everything is ESLint v9 compatible. Both Next.js ESLint packages (the config and the plugin) still use classic configuration files (RC) and NOT flat config, which means you need to use the FlatCompat mode if you want to use them "as is" in your flat config
 * There are also features like **PPR** (which we will not use it in this tutorial) that work already well today but are still **experimental**, meaning you need to use a canary version and then enable the feature in the Next.js configuration.
 
 ## Next.js 14 version of this tutorial

app/web_development/tutorials/next-js-static-first-mdx-starterkit/nextjs-mdx-setup/page.mdx

@@ -370,14 +370,14 @@ Because we used **create next app** in our tsconfig.json, we **already** have th
 
 ## Tips when using MDX
 
-Now that our MDX setup is done, you might be interested in a few tips that make life easier when writing MDX / markdown in VSCode, if you do check out the ["VSCode markdown (and MDX) related tips" chapter](/web_development/posts/vscode#vscode-markdown-and-mdx-related-tips) in the VSCode post
+Now that our MDX setup is done, you might be interested in a few tips that make life easier when writing MDX / markdown in VSCode, if you do check out the ["VSCode markdown (and MDX) related tips" chapter](/web_development/posts/vscode#vscode-mdx-and-markdown-extensions) in the VSCode post
 
 Congratulations 🎉 you now have MDX support added to your project using next/mdx, in other parts of this tutorial, we will further extend that setup by adding several valuable plugins and learning how to use custom react components to fully benefit from what MDX has to offer
 
 <DonationsMessage />
 
 > [!MORE]  
-> [chris.lu "MDX and markdown in VSCode tips"](/web_development/posts/vscode#vscode-markdown-and-mdx-related-tips)  
+> [chris.lu "MDX and markdown in VSCode tips"](/web_development/posts/vscode#vscode-mdx-and-markdown-extensions)  
 
 <Pagination
     previous={{ label: 'Content Security Policy (CSP)', href: '/web_development/tutorials/next-js-static-first-mdx-starterkit/content-security-policy' }}

app/web_development/tutorials/next-js-static-first-mdx-starterkit/optimizing-using-next-image/page.mdx

@@ -54,7 +54,7 @@ This page is all about using [next/image](https://nextjs.org/docs/app/api-refere
 By using **next/image** we will make sure that all images we put into our MDX pages get optimized, which means that:
 
 * we will update the configuration to make sure our [PNG](https://web.dev/learn/images/png) or [JPG](https://web.dev/learn/images/jpeg) images get converted automatically into formats like [WEBP](https://web.dev/learn/images/webp) and [AVIF](https://web.dev/learn/images/avif); this will reduce the file sizes of images without them losing in quality, which means our images will consume less bandwidth and load faster
-* we will use **next/image**, which will help us make our images [responsive](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) by creating a srcset to define multiple versions of an image that have different dimensions, so that on small screens we small images that are NOT heavier than necessary and on big screens we load bigger images to make sure the browser does not fetch a small image and then upscale it, which would make it look blurry
+* we will use **next/image**, which will help us make our images [responsive](https://developer.mozilla.org/en-US/docs/Web/HTML/Responsive_images) by creating a srcset to define multiple versions of an image that have different dimensions, so that on small screens we small images that are NOT heavier than necessary and on big screens we load bigger images to make sure the browser does not fetch a small image and then upscale it, which would make it look blurry
 * we will also use a remark plugin to make sure the path of each image gets turned into an import, which will allow **next/image** to determine the width and height of our images automatically
 
 We will also keep the drag and drop images feature that improves the **developer experience (DX)** in VSCode intact by making sure that adding images to a document is easy and quick when using VSCode. What is great is that after you **drag and drop** an image into a document VSCode will create the markdown element with the correct path to the image
@@ -65,7 +65,7 @@ We will also keep the drag and drop images feature that improves the **developer
 > [!MORE]  
 > [Next.js "next/image" API reference](https://nextjs.org/docs/app/api-reference/components/image)  
 > [Next.js "Image Optimization" documentation](https://nextjs.org/docs/app/building-your-application/optimizing/images)  
-> [MDN "Responsive images" documentation](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)  
+> [MDN "Responsive images" documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Responsive_images)  
 > [Aurora team "Building an effective Image Component" article](https://developer.chrome.com/docs/aurora/image-component)  
 
 ## How to **NOT** add images to an MDX document

app/web_development/tutorials/next-js-static-first-mdx-starterkit/styling-and-css/page.mdx

@@ -503,13 +503,13 @@ Lines 22 to 31: we use the **html** [type selector](https://developer.mozilla.or
 * then we also set the [text-size-adjust](https://developer.mozilla.org/en-US/docs/Web/CSS/text-size-adjust) CSS property, this feature makes sure that on mobile browsers, the text size is exactly the one we set and not inflated by the browser, this helps to avoid weird placement bugs where modified text size moves other elements around; however, if you use this feature make sure that your text is easy to read on mobile devices and tablets, if the text is too small I recommend using a bigger font-size and always keep the **text-size-adjust** set to 100%, text-size-adjust is however only supported on chrome (as of now); you can check out what browser support it on [caniuse "text-size-adjust"](https://caniuse.com/text-size-adjust)
 * we also use the [tab-size](https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size) CSS property, which is useful if, for example, you have code blocks in your content, as code blocks often contain tabs for code indentation, which means this feature is similar to setting the indent size in your [.editorconfig](https://editorconfig.org/) file, if you use just a number without a unit (like in this example) then tab size will be that number multiplied by the **width** of one space (this is MOT the font-size, which is the height of your characters); so setting it to **4** and assuming a space character is 9px wide then this gives us a tab size width of `4 x 9 = 36px`
 * then we set the **color** for our **background** and the default color for our **text** using the CSS [var()](https://developer.mozilla.org/en-US/docs/Web/CSS/var) function and as value we use the colors we previously defined in the `:root` pseudo element
-* finally, we set the **font-size** to **100%**, which is good for accessibility as it lets the user change the font-size via the browser settings; as we will also use the [CSS rem unit](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units) for all font related sizes, this means that setting the font-size of the HTML element will have an impact on all other font-sizes in our CSS; for example, we use the CSS rem unit for the font-size of all our headings, if the user now changes the default font-size via the browser settings then all our text will adapt to that change but also all the headings will get adjusted based on the new default font-size; however, if you would have set a static value like 16px as font-size to your `<html>{:html}` element (or the `<body>{:html}` element) then the user would NOT be able to change the font-size via the browser settings, as their settings would have no effect, the font would still be 16px
+* finally, we set the **font-size** to **100%**, which is good for accessibility as it lets the user change the font-size via the browser settings; as we will also use the [CSS rem unit](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units) for all font related sizes, this means that setting the font-size of the HTML element will have an impact on all other font-sizes in our CSS; for example, we use the CSS rem unit for the font-size of all our headings, if the user now changes the default font-size via the browser settings then all our text will adapt to that change but also all the headings will get adjusted based on the new default font-size; however, if you would have set a static value like 16px as font-size to your `<html>{:html}` element (or the `<body>{:html}` element) then the user would NOT be able to change the font-size via the browser settings, as their settings would have no effect, the font would still be 16px
 
 Lines 33 to 36: we use the **body type selector** and reset the margin value(s) that a browser might set by default, to zero
 
 Lines 38 to 45: we add some margin to the **footer** and **header** using the respective type selectors, we also add a minimum height to the footer, which will create a bit of space at the end of our pages, this is useful as on mobile and tablet you sometimes have a device or browser UI that will put something on the bottom of the screen that would be over your last bit of content, making the bottom part hard to read or even prevent interacting with something in your page. By adding a bit of space you ensure that the user will always see all of your content (when the page is fully scrolled down)
  
-Lines 47 to 53: we use the **main type selector** to tell the browser that we want to use the [CSS Flexbox layout](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox) by setting the **display** property to [flex](https://developer.mozilla.org/en-US/docs/Web/CSS/display#flex); for this element we set a maximum width using the CSS variable we created in the `:root`, the maximum width is 1120px to ensure that even on very large viewports (screens) the main element will not stretch to the full available width, this is important for the text we will place inside of our main section because if chapters of the text are very wide, it makes them hard to read; we set both the margin-left and margin-left to auto to make sure that our `<main>{:html}` element will get centered if the viewport is wider than the **max-width** we just set; finally, we also add a little bit of margin to the bottom to make sure there is a bit of space between our content and the footer of the page
+Lines 47 to 53: we use the **main type selector** to tell the browser that we want to use the [CSS Flexbox layout](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) by setting the **display** property to [flex](https://developer.mozilla.org/en-US/docs/Web/CSS/display#flex); for this element we set a maximum width using the CSS variable we created in the `:root`, the maximum width is 1120px to ensure that even on very large viewports (screens) the main element will not stretch to the full available width, this is important for the text we will place inside of our main section because if chapters of the text are very wide, it makes them hard to read; we set both the margin-left and margin-left to auto to make sure that our `<main>{:html}` element will get centered if the viewport is wider than the **max-width** we just set; finally, we also add a little bit of margin to the bottom to make sure there is a bit of space between our content and the footer of the page
 
 > [!NOTE]  
 > When choosing to use the **CSS Flexbox layout** as we did for the main element, the browser automatically assumes that the [flex-flow](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-flow) is set to row, which means that if we put an `<article>{:html}` into our `<main>{:html}` as well as an `<aside>{:html}` then both will get displayed as two columns next to each other (yes flex-flow row creates "columns")
@@ -525,7 +525,7 @@ Lines 70 to 72: we use the [margin-block](https://developer.mozilla.org/en-US/do
 > [!NOTE]  
 > Both **rem** and **em** are so called relative units, for example rem is relative to the font-size you have defined in the root element, which is why rem actually means **root em**, the root element of a HTML document is the `<html>{:html}` element (not the `<body>{:html}` element)
 >  
-> an em is a bit more complex to understand, but there is a very good explanation in the [MDN "CSS values and units" documentation](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths) so I will quote them:
+> an em is a bit more complex to understand, but there is a very good explanation in the [MDN "CSS values and units" documentation](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#lengths) so I will quote them:
 >  
 > > The em unit means "my parent element's font-size" if used for font-size (and "my own font-size" when used for anything else)  
 >  
@@ -591,10 +591,9 @@ Congratulations 🎉 you now know how to use CSS modules and global.css to add s
 <DonationsMessage />
 
 > [!MORE]  
-> [Next.js "global styles" documentation](https://nextjs.org/docs/app/building-your-application/styling/css-modules#global-styles)  
 > [MDN "CSS" documentation](https://developer.mozilla.org/en-US/docs/Web/CSS)  
 > [MDN "Using CSS custom properties (variables)" documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)  
-> [MDN "Flexbox" documentation](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox)  
+> [MDN "Flexbox" documentation](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox)  
 
 <Pagination
     previous={{ label: 'Linting in VSCode using ESLint and MDX extensions', href: '/web_development/tutorials/next-js-static-first-mdx-starterkit/linting-using-vscode-and-extensions' }}

app/web_development/tutorials/next-js-static-first-mdx-starterkit/table-of-contents-plugin/page.mdx

@@ -241,7 +241,7 @@ Lines 223 to 225: we remove the default padding from the `<ul>{:html}` that the
 >  
 > the 2nd one is that you need to make sure you also specify at least one of the 4 properties **top**, **left**, **right** or **bottom** (for the element you want to be sticky), for example in the example above if we remove the **top** property then the `<nav>{:html}` element wouldn't be sticky anymore
 >  
-> the third one that is important is that you don't set the height (of element that you want to be sticky) to 100%, you need to define a height, what works however is to use the vh [CSS unit](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units) (viewport height), so for example if you want the sticky aside to be as tall as the page minus the header (that for example is 50px tall), then you could use something like this:
+> the third one that is important is that you don't set the height (of element that you want to be sticky) to 100%, you need to define a height, what works however is to use the vh [CSS unit](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units) (viewport height), so for example if you want the sticky aside to be as tall as the page minus the header (that for example is 50px tall), then you could use something like this:
 >  
 > `height: calc(100vh - 50px);{:css}`