logo
pub

Nouvelles fonctionnalités dans la V.1

authors

Series: Blog Starter

Episodes: (2/4)

Vue d'ensemble

Un article sur les nouvelles fonctionnalités introduites dans la v1.0. Nouvelles fonctionnalités:

Le premier chargement de JS est passé de 43 Ko à 39 Ko malgré toutes les nouvelles fonctionnalités ajoutées ! 1

Consultez le guide de mise à niveau ci-dessous si vous migrez à partir de la version v0 du modèle.

Couleurs du thème

Vous pouvez facilement modifier la couleur du thème en modifiant l'attribut principal dans le fichier de configuration tailwind:

tailwind.config.js
theme: {
    colors: {
      primary: colors.teal,
      gray: colors.neutral,
      ...
    }
  ...
}

L'attribut de couleur primaire doit se voir attribuer un objet avec des clés de 50, 100, 200 ... 900 et les valeurs de code couleur correspondantes.

Tailwind comprend d'excellentes palettes de couleurs par défaut qui peuvent être utilisées pour créer un thème pour votre propre site Web. Consultez la page de documentation sur la personnalisation des couleurs pour connaître la gamme complète d'options.

Vous migrez depuis la v1? Vous pouvez revenir au thème précédent en définissant «primary» sur «colors.sky» (Tailwind 2.2.2 et supérieur, sinon «colors.lightBlue») et en changeant le gris en «colors.gray».

Depuis la v1.1.2+, vous pouvez également personnaliser facilement le style de vos blocs de code en modifiant la feuille de style css/prism.css. Les noms de classes de jetons sont compatibles avec prismjs afin que vous puissiez copier et adapter les styles de jetons à partir d'une feuille de style prismjs, par exemple. thèmes prisme.

Compilateur Xdm MDX

Nous avons basculé le bundler MDX de next-mdx-remote vers mdx-bundler. Cela utilise xdm sous le capot, les dernières bibliothèques Micromark 3 et Remark, Rehype.

Avertissement : Si vous utilisiez des bibliothèques de remark ou de rehype personnalisées, veuillez effectuer une mise à niveau vers celles compatibles Micromark 3. Si vous effectuez une mise à niveau, veuillez supprimer node_modules et package-lock.json pour éviter d'avoir des problèmes liés aux dépendances passées.

xdm contient plusieurs améliorations par rapport à @mdx-js/mdx, le compilateur utilisé en interne par next -mdx-remote, mais il peut y avoir des changements de comportement importants. Veuillez vérifier votre sortie markdown pour vérifier.

Certaines nouvelles possibilités incluent le chargement de composants directement dans le fichier mdx en utilisant la syntaxe d'importation et l'inclusion de code js qui pourrait être compilé et regroupé lors de l'étape de construction.

Par exemple, l'extrait jsx suivant peut être utilisé directement dans un fichier MDX pour afficher le composant de titre de page:

// Or import PageTitle from './components/PageTitle.js' if you are using js
import PageTitle from './components/PageTitle.tsx'
;<PageTitle> Using JSX components in MDX </PageTitle>

La configuration par défaut résout tous les composants relatifs au répertoire components.

Note: Les composants qui nécessitent des chargeurs d'images externes nécessitent également une configuration esbuild supplémentaire. Les composants qui dépendent de l'état global de l'application sur le cycle de vie, comme le composant Nextjs Link, ne fonctionneraient pas non plus avec cette configuration car chaque fichier mdx est construit indépendamment. Dans de tels cas, il est préférable d'utiliser la substitution de composants.

Composant table des matières

Inspiré par Docusaurus et la [gatsby-remark-table-of-contents](https://www.gatsbyjs.com/ plugins/gatsby-remark-table-of-contents/), la variable toc contenant tous les en-têtes de niveau supérieur du document est transmise au fichier MDX et peut être stylisée en conséquence. Pour simplifier la génération d'une table des matières (TOC), vous pouvez utiliser le composant TOCInline existant.

Par exemple, la table des matières de cet article a été générée avec le code suivant:

<TOCInline toc={props.toc} exclude="Overview" toHeading={2} />

Vous pouvez personnaliser les titres affichés en configurant les accessoires « fromHeading » et « toHeading », ou exclure des titres particuliers. en passant une chaîne ou un tableau de chaînes à la prop exclude. Par défaut, tous les titres de profondeur 3 ou inférieure sont en retrait. Cela peut être configuré en modifiant la propriété « indentDepth ». Un accessoire asDisclosure peut être utilisé pour restituer la table des matières dans un élément de divulgation extensible.

Voici la table des matières complète rendue dans un élément de divulgation.

<TOCInline toc={props.toc} asDisclosure />
Table of Contents

Layouts

Vous pouvez mapper le contenu du blog mdx aux composants de mise en page en configurant le champ frontmatter. Par exemple, cet article est écrit avec la nouvelle mise en page « PostSimple » !

Ajouter de nouveaux modèles

Les modèles de mise en page sont stockés dans le dossier ./layouts. Vous pouvez ajouter vos composants React que vous souhaitez mapper au contenu markdown dans ce dossier. Le nom du fichier de composant doit correspondre à celui spécifié dans le champ «layout» du frontmatter markdown.

Le seul champ obligatoire est «enfants» qui contient le contenu MDX rendu, bien que vous souhaitiez probablement transmettre le contenu de frontMatter et le restituer dans le modèle.

Vous pouvez configurer le modèle pour qu'il prenne en compte d'autres champs - voir le composant PostLayout pour un exemple.

Voici un exemple de mise en page que vous pouvez personnaliser davantage:

export default function ExampleLayout({ frontMatter, children }) {
  const { date, title } = frontMatter

  return (
    <SectionContainer>
      <div>{date}</div>
      <h1>{title}</h1>
      <div>{children}</div>
    </SectionContainer>
  )
}

Configuration d'un article de blog frontmatter

Utilisez le champ frontmatter layout pour spécifier le modèle auquel vous souhaitez mapper la publication markdown. Voici à quoi ressemble le contenu de cet article:

---
title: 'Nouvelles fonctionnalités dans la V.1'
date: '2021-05-26   '
tags: ['next-js', 'tailwind', 'guide']
draft: false
summary: 'Présentation des nouvelles fonctionnalités du modèle de mise en page - vous pouvez mapper le contenu du blog mdx aux composants de mise en page en configurant le champ frontmatter'
layout: PostSimple
---

Vous pouvez configurer la mise en page par défaut dans la section de page respective en modifiant la variable DEFAULT_LAYOUT. La page DEFAULT_LAYOUT pour les articles de blog est définie sur PostLayout.

Etendre

layout est mappé au wrapper qui enveloppe l'intégralité du contenu MDX.

export const MDXComponents = {
  Image,
  a: CustomLink,
  pre: Pre,
  wrapper: ({ components, layout, ...rest }) => {
    const Layout = require(`../layouts/${layout}`).default
    return <Layout {...rest} />
  },
}

export const MDXLayoutRenderer = ({ layout, mdxSource, ...rest }) => {
  const MDXLayout = useMemo(() => getMDXComponent(mdxSource), [mdxSource])

  return <MDXLayout layout={layout} components={MDXComponents} {...rest} />
}

Utilisez le composant MDXLayoutRenderer sur une page sur laquelle vous souhaitez accepter un nom de mise en page à mapper à la mise en page souhaitée. Vous devez transmettre le nom de la mise en page du dossier de mise en page (il doit correspondre exactement).

Analytique

Le modèle prend désormais en charge plausible, simple Analytics et Google Analytics. Configurez « siteMetadata.js » avec les paramètres qui correspondent au fournisseur d'analyse souhaité.

analytics: {
    // supports plausible, simpleAnalytics or googleAnalytics
    plausibleDataDomain: '', // e.g. tailwind-nextjs-starter-blog.vercel.app
    simpleAnalytics: false, // true or false
    googleAnalyticsId: '', // e.g. UA-000000-2 or G-XXXXXXX
  },

Les événements personnalisés sont également pris en charge. Vous pouvez importer la fonction logEvent à partir du fichier @components/analytics/[ANALYTICS-PROVIDER] et l'appeler lorsque déclenchant certains événements intéressants. Remarque: Une configuration supplémentaire peut être requise en fonction du fournisseur d'analyses, veuillez consulter leur site officiel documentation pour plus d'informations.

Système de commentaires du blog

Nous avons également ajouté la prise en charge de giscus, utterances ou disqus. Pour l'activer, configurez simplement la propriété de commentaires « siteMetadata.js » avec le fournisseur et les paramètres souhaités tels que spécifiés dans le fichier de configuration.

comment: {
    // Select a provider and use the environment variables associated to it
    // https://vercel.com/docs/environment-variables
    provider: 'giscus', // supported providers: giscus, utterances, disqus
    giscusConfig: {
      // Visit the link below, and follow the steps in the 'configuration' section
      // https://giscus.app/
      repo: process.env.NEXT_PUBLIC_GISCUS_REPO,
      repositoryId: process.env.NEXT_PUBLIC_GISCUS_REPOSITORY_ID,
      category: process.env.NEXT_PUBLIC_GISCUS_CATEGORY,
      categoryId: process.env.NEXT_PUBLIC_GISCUS_CATEGORY_ID,
      mapping: 'pathname', // supported options: pathname, url, title
      reactions: '1', // Emoji reactions: 1 = enable / 0 = disable
      // Send discussion metadata periodically to the parent window: 1 = enable / 0 = disable
      metadata: '0',
      // theme example: light, dark, dark_dimmed, dark_high_contrast
      // transparent_dark, preferred_color_scheme, custom
      theme: 'light',
      // theme when dark mode
      darkTheme: 'transparent_dark',
      // If the theme option above is set to 'custom`
      // please provide a link below to your custom theme css file.
      // example: https://giscus.app/themes/custom_example.css
      themeURL: '',
    },
    utterancesConfig: {
      // Visit the link below, and follow the steps in the 'configuration' section
      // https://utteranc.es/
      repo: process.env.NEXT_PUBLIC_UTTERANCES_REPO,
      issueTerm: '', // supported options: pathname, url, title
      label: '', // label (optional): Comment 💬
      // theme example: github-light, github-dark, preferred-color-scheme
      // github-dark-orange, icy-dark, dark-blue, photon-dark, boxy-light
      theme: '',
      // theme when dark mode
      darkTheme: '',
    },
    disqus: {
      // https://help.disqus.com/en/articles/1717111-what-s-a-shortname
      shortname: process.env.NEXT_PUBLIC_DISQUS_SHORTNAME,
    },
  },

Auteurs multiples

Les informations sur les auteurs sont désormais séparées de « siteMetadata.js » et stockées dans son propre dossier « data/authors » en tant que fichier markdown. Au minimum, vous aurez besoin d'un fichier « default.md » avec les informations de paternité. Vous pouvez créer des fichiers supplémentaires selon vos besoins et le nom du fichier sera utilisé comme référence à l'auteur.

Voici à quoi pourrait ressembler un fichier markdown d'auteur :

default.md
---
name: Tails Azimuth
avatar: /static/images/avatar.png
occupation: Professeur de sciences atmosphériques
company: Université de Stanford
email: [email protected]
twitter: https://twitter.com/Twitter
linkedin: https://www.linkedin.com
github: https://github.com
---

Longue description de vous...

Vous pouvez utiliser ces informations à plusieurs endroits du modèle. Par exemple, dans la section à propos de la page, nous récupérons les informations par défaut sur l'auteur avec cette ligne de code:

const authorDetails = await getFileBySlug('authors', ['default'])

Ceci est rendu dans le modèle AuthorLayout.

Plusieurs auteurs dans le billet de blog

Le texte d'un article de blog accepte un champ de tableau «auteurs» facultatif. Si aucun champ n'est spécifié, on suppose que l'auteur par défaut est utilisé. Transmettez simplement un tableau d'auteurs pour afficher plusieurs auteurs associés à une publication.

Par exemple, le texte suivant affichera les auteurs donnés par data/authors/default.md et data/authors/sparrowhawk.md

title: 'My first post'
date: '2021-01-12'
draft: false
summary: 'My first post'
authors: ['default', 'sparrowhawk']

Une démo d'un article de plusieurs auteurs est présentée dans Introducing Tailwind Nextjs Starter Blog post.

Bouton Copier pour les blocs de code

Passez la souris sur un bloc de code et vous remarquerez un bouton de copie inspiré de GitHub ! Vous pouvez modifier ./components/Pre.js pour le personnaliser davantage. Le composant est passé à MDXComponents et modifie tous les blocs <pre>.

Mise en surbrillance des lignes et numéros de ligne

La mise en évidence des lignes et les numéros de ligne sont désormais pris en charge dès le départ grâce au nouveau plug-in rehype-prism-plus

Le bloc de code javascript suivant:

```js {1, 3-4} showLineNumbers
var num1, num2, sum
num1 = prompt('Enter first number')
num2 = prompt('Enter second number')
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
alert('Sum = ' + sum) // "+" means combine into a string
```

apparaitra comme ceci

var num1, num2, sum
num1 = prompt('Enter first number')
num2 = prompt('Enter second number')
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
alert('Sum = ' + sum) // "+" means combine into a string

Pour modifier les styles, changez les sélecteurs de classe suivants dans le fichier prism.css :

.code-highlight {
  @apply float-left min-w-full;
}

.code-line {
  @apply -mx-4 block border-l-4 border-opacity-0 pl-4 pr-4;
}

.code-line.inserted {
  @apply bg-green-500 bg-opacity-20;
}

.code-line.deleted {
  @apply bg-red-500 bg-opacity-20;
}

.highlight-line {
  @apply -mx-4 border-l-4 border-primary-500 bg-gray-700 bg-opacity-50;
}

.line-number::before {
  @apply -ml-2 mr-4 inline-block w-4 text-right text-gray-400;
  content: attr(line);
}

Composant Newsletter (v1.1.3)

Introduit dans la v1.1.3, le composant newsletter vous offre un moyen simple de créer une audience. Il s'intègre aux fournisseurs suivants:

Pour l'utiliser, spécifiez le fournisseur que vous utilisez dans le fichier de configuration et ajoutez les variables d'environnement nécessaires au fichier .env. Pour plus d'informations sur les variables requises, consultez .env.sample.

Deux composants sont exportés, un composant NewsletterForm par défaut et un composant BlogNewsletterForm, qui est également transmis en tant que composant MDX. et peut être utilisé dans un article de blog:

<BlogNewsletterForm title="Like what you are reading?" />
Subscribe to the newsletter

Le composant s'appuie sur les [routes API] de nextjs (https://nextjs.org/docs/api-routes/introduction) qui nécessitent la configuration d'une instance côté serveur de nextjs. et n'est pas compatible avec un export de site 100% statique. Les utilisateurs doivent soit s'auto-héberger, soit utiliser une plate-forme compatible comme Vercel ou Netlify qui prend en charge cette fonctionnalité.

Une alternative compatible avec les sites statiques consiste à remplacer l'itinéraire dans le composant de newsletter par un fournisseur de point de terminaison d'API de formulaire.

Bibliographie et citations (v1.2.1)

Le plugin rehype-citation est ajouté au pipeline de traitement xdm dans la v1.2.1. Cela vous permet de formater facilement des citations et d'insérer une bibliographie à partir d'un fichier bibtex ou CSL-json existant.

Par exemple, l'exemple de code remark suivant:

Standard citation [@Nash1950]
In-text citations e.g. @Nash1951
Multiple citations [see @Nash1950; @Nash1951, page 50]

**References:**

[^ref]

sera rendu ainsi:

Standard citation (Nash, 1950)
In-text citations e.g. Nash (1951)
Multiple citations (see Nash, 1950, 1951, p. 50)

References:

Nash, J. (1950). Equilibrium points in n-person games. Proceedings of the National Academy of Sciences, 36(1), 48–49.
Nash, J. (1951). Non-cooperative games. Annals of Mathematics, 286–295.

Une bibliographie sera insérée à la fin du document, mais elle peut être écrasée en spécifiant une balise [^Ref] à l'emplacement prévu. Le plugin utilise la formation de citations APA, mais prend également en charge les CSL suivants, « apa », « vancouver », « harvard1 », « chicago », « mla », ou un chemin vers un fichier CSL spécifié par l'utilisateur.

Voir rehype-citation readme pour plus d'informations sur les options de configuration.

Police d'écriture auto-hébergée (v1.5.0)

La police Google a été remplacée par la police auto-hébergée de Fontsource. Cela donne les avantages suivants:

L'auto-hébergement apporte des gains de performances significatifs, car le chargement de polices à partir de services hébergés, tels que Google Fonts, entraîne une requête réseau supplémentaire (bloquant le rendu). Pour donner une perspective, pour les sites Web simples, il a été constaté que les temps de chargement visuels étaient doublés.

Les polices restent verrouillées en version. Google propose souvent des mises à jour de ses polices sans préavis, ce qui peut interférer avec vos projets de production en direct. Gérez vos polices comme n'importe quelle autre dépendance NPM.

S'engager à respecter la confidentialité. Google suit l'utilisation de leurs polices et pour ceux qui sont extrêmement préoccupés par la confidentialité, l'auto-hébergement est une alternative.

Cela conduit à un ensemble de polices plus petit et à un temps de chargement plus rapide de 0,1 seconde ([comparaison webpagetest](https://www.webpagetest.org/video/compare.php?tests=220201_AiDcFH_f68a69b758454dd52d8e67493fdef7da,220201_BiDcMC_bf2d53f14483814ba61e794 311dfa771)).

Pour modifier la police Inter par défaut:

  1. Installez la police préférée - npm install -save @fontsource/<font-name>
  2. Mettez à jour l'importation dans pages/_app.js- import '@fontsource/<font-name>.css'
  3. Mettez à jour la propriété fontfamily dans le fichier de configuration CSS tailwind

Guide de mise à niveau

Des parties importantes du code ont été modifiées de la v0 à la v1, notamment la prise en charge des mises en page et un nouveau moteur mdx.

Il n'y a pas non plus de réelle raison de changer si le précédent répond à vos besoins et il pourrait être plus facile de le copier. le composant change qui vous intéresse sur votre blog existant plutôt que de tout migrer.

Néanmoins, si vous souhaitez le faire et que vous n'avez pas beaucoup modifié le modèle, vous pouvez cloner la nouvelle version et copier l'article de blog vers le nouveau modèle.

Une autre alternative serait d'extraire la dernière version du modèle avec le code suivant:

git remote add template [email protected]:timlrx/tailwind-nextjs-starter-blog.git
git pull template v1 --allow-unrelated-histories
rm -rf node_modules

Vous pouvez voir un exemple d'une telle migration dans ce commit pour mon blog personnel.

La v1 utilise également feed.xml plutôt que index.xml, pour éviter certains problèmes de construction avec Vercel. Si vous migrez, vous devez ajouter une redirection vers « next.config.js » comme ceci:

async redirects() {
  return [
    {
      source: '/:path/index.xml',
      destination: '/:path/feed.xml',
      permanent: true,
    }
  ]
}

Footnotes

  1. Avec les nouvelles modifications apportées à Nextjs 12, le premier chargement de JS passe à 45 Ko. ↩

SHARE