Ultimamente sono davvero preso da Fumadocs. Il set di funzioni di base è già ottimo così com’è, ma ho deciso di personalizzare alcune cose per renderlo più comodo. Spero che tutto questo possa esserti utile se stai cercando di migliorare la tua configurazione.

Personalizzare Fumadocs: Alcune nuove funzionalità che ho aggiunto

Un componente per l’incorporamento di video YouTube

Il componente <YouTubeEmbed> ti permette di incorporare i video di YouTube in modo sicuro.

mdx
<YouTubeEmbed videoId="LX6A3OmY4uk" title="Video Title" />

Questo componente ha diverse proprietà interessanti:

  • È responsive (mantiene un rapporto di aspetto 16:9)
  • Imposta automaticamente i giusti attributi di sicurezza
  • È ottimizzato per le prestazioni (caricamento differito o lazy loading)

Un componente per la visualizzazione di percorsi UI

Il componente <UiPath> consente di mostrare visivamente una sequenza di passaggi di un’interfaccia utente.

mdx
<UiPath>Email activity > Has a hard bounced delivery > Yes</UiPath>

Questo componente ha diverse proprietà interessanti:

  • Analizza automaticamente un percorso separato da >
  • Renderizza ogni passaggio come un chip
  • Evidenzia il passaggio finale con uno stile “attivo” (sfondo blu)
  • Separa i passaggi con una freccia (›)

Lo stile è definito in app/globals.css, utilizzando le seguenti classi:

  • .ui-chip: lo stile predefinito del chip (sfondo grigio)
  • .ui-chip.is-active: lo stile del chip attivo (sfondo blu)
  • .ui-sep: lo stile per il carattere separatore (›)

Visualizzazione della data dell’articolo e avvisi per articoli non aggiornati

Se imposti created e updated nel frontmatter di un file MDX, la pagina dell’articolo mostrerà automaticamente le date di creazione e dell’ultimo aggiornamento.

mdx
---
title: Article Title
created: 2021-04-18
updated: 2024-02-28
---
  • created: la data di creazione dell’articolo
  • updated: la data dell’ultimo aggiornamento dell’articolo (non viene mostrata se coincide con la data di creazione)

Inoltre, qualsiasi articolo che non sia stato aggiornato da oltre un anno mostrerà automaticamente il seguente avviso:

Questo articolo non viene aggiornato da oltre un anno. Le informazioni potrebbero non essere più attuali…

Questa funzionalità è implementata in components/article-dates.tsx e viene renderizzata direttamente sotto il titolo dell’articolo.

Visualizzazione degli articoli correlati

Il componente <RelatedArticles> ti permette di mostrare articoli correlati all’interno di un post.

mdx
<RelatedArticles related="blog-japanese,css,embed-html" />

Funzionalità:

  • Specifica gli slug dei nomi dei file (es. blog-japanese), separati da virgola
  • Funziona sia con le cartelle tra parentesi ((pagecreate)/blog-japanese.mdx) che con quelle normali (payment/cant-free-trial.mdx)
  • Mostra il titolo di ogni articolo e un badge della categoria
  • Un design a scheda in stile blocco di codice con sfondo bianco
  • Un’icona Zap accanto al titolo e un’icona NotebookText accanto a ciascun articolo
  • Nessuna sottolineatura sui link, con un cambio di colore al passaggio del mouse (hover)

Esempio di utilizzo:

mdx
---
title: Creating a Blog Post
---

## Body

Here are some related articles.

<RelatedArticles related="blog-japanese,css,embed-html" />

Funziona correttamente anche se ci sono spazi attorno alle virgole:

mdx
<RelatedArticles related="blog-japanese, css, embed-html" />

File di implementazione:

  • components/related-articles.tsx: il componente di visualizzazione degli articoli correlati
  • lib/getPageBySlug.ts: una funzione di supporto per recuperare una pagina a partire dal suo slug
    • getPageBySlug(slug): recupera una singola pagina da uno slug
    • getPagesBySlugs(slugs): recupera più pagine da un elenco di slug
    • getCategoryTitleFromPage(page): ottiene il titolo di una categoria da una pagina

Dettagli tecnici:

  • Memorizza nella cache la mappa da slug a pagina per ottimizzare le prestazioni
  • Determina automaticamente la categoria dal percorso del file (incluse le cartelle tra parentesi)
  • Le informazioni sulla categoria vengono estratte da meta.json o index.mdx, utilizzando una cache in memoria

Funzionalità della homepage

La homepage (content/docs/index.mdx) include le seguenti funzionalità implementate.

Articoli aggiunti e aggiornati di recente

Mostra gli articoli che hanno created o updated impostati nel proprio frontmatter, ordinati per data.

mdx
import { RecentCreatedPosts, RecentUpdatedPosts } from '@/components/recent-posts';

## Recently Added Articles

<RecentCreatedPosts limit={10} />

## Recently Updated Articles

<RecentUpdatedPosts limit={10} />

Funzionalità:

  • Ogni articolo viene visualizzato come una scheda, con un effetto al passaggio del mouse
  • Un’icona FileText appare prima del titolo di ogni articolo
  • Vengono mostrati i badge delle categorie (es. Fatturazione, Prodotti/Lezioni)
  • Le date non vengono mostrate: si tratta di un formato a elenco semplice

File di implementazione:

  • components/recent-posts.tsx: il componente di visualizzazione dell’elenco degli articoli
  • lib/recent-posts.ts: le funzioni di recupero degli articoli (getRecentCreatedPosts, getRecentUpdatedPosts)

Argomenti e articoli in evidenza (Visualizzazione basata sulle categorie)

Un componente shortcode che mostra fino a 5 articoli per categoria.

mdx
import { CategoryPosts } from '@/components/category-posts';

## Featured Topics & Articles

<CategoryPosts category="payment" limit={5} />

<CategoryPosts category="product" limit={5} />

<CategoryPosts category="students" limit={5} />

Funzionalità:

  • I nomi delle categorie sono mostrati come link e, facendo clic su uno di essi, si naviga alla pagina della categoria
  • Un’icona BookText appare prima di ogni articolo
  • Gli articoli sono ordinati in base all’ultimo aggiornamento (o alla data di creazione, in assenza di una data di aggiornamento)
  • Puoi riordinare le sezioni modificando l’ordine delle chiamate a <CategoryPosts /> nel file MDX

Un piè di pagina condiviso viene mostrato in tutto il sito. È implementato in components/footer.tsx.

Layout:

  • Un design responsive a due colonne (affiancate sugli schermi grandi, impilate sui dispositivi mobili)
  • Colonna di sinistra: logo del sito, descrizione, icone dei social media e informazioni sull’utente connesso
  • Colonna di destra: avvisi del sito (termini di servizio, informazioni sugli aggiornamenti, ecc.)

Cosa contiene la colonna di sinistra:

  • Titolo del sito (collegato a /docs)
  • Descrizione del sito
  • Icone dei social media (GitHub, Discord, YouTube, Twitter/X)
  • Informazioni sull’utente connesso (segnaposto)
    • Stato “Connesso”
    • Visualizzazione del nome utente
    • Pulsanti di disconnessione / modifica password

Cosa contiene la colonna di destra:

  • Descrizione del sito e avvisi
  • Una nota su come vengono aggiornate le informazioni
  • Una nota su come vengono aggiunti i nuovi articoli

File di implementazione:

  • components/footer.tsx: il componente del footer
  • app/layout.tsx: aggiunge il footer al layout radice (root layout)

Il piè di pagina viene mostrato automaticamente su ogni pagina ed è stilizzato utilizzando le variabili di tema di Fumadocs.