feat(callouts): callout Notion-style come admonition Docusaurus

docs/callouts-demo.mdx

@@ -0,0 +1,99 @@
+---
+title: Callouts — demo visivo
+slug: /callouts-demo
+unlisted: true
+---
+
+Pagina temporanea per QA visivo dei 13 callout Notion-style.
+`unlisted: true` la tiene fuori da sidebar e sitemap; raggiungibile solo via URL diretto `/docs/callouts-demo`.
+Eliminare a feature accettata (o spostare in `docs/reference/callouts.mdx`).
+
+## Nuovi tipi (9)
+
+:::prereq
+Quali esercizi devono essere già stati completati e quali parti di teoria devono essere già state studiate per riuscire a portare a termine l'esercizio.
+:::
+
+:::learn
+Un elenco dei concetti che verranno messi in pratica e delle competenze da sviluppare.
+:::
+
+:::exercise
+Un elenco dei concetti che verranno messi in pratica con questo esercizio e delle competenze da sviluppare.
+:::
+
+:::definition
+Qui troverai le (poche) definizioni di teoria.
+:::
+
+:::history
+Qui troverai approfondimenti storici sui concetti esposti o collegamenti interdisciplinari con altre materie.
+:::
+
+:::code
+Questi sono dettagli aggiuntivi sulla sintassi nel linguaggio di programmazione o inviti a provare del codice. Esempio:
+
+```python
+def saluta(nome: str) -> str:
+    return f"Ciao, {nome}!"
+
+print(saluta("mondo"))
+```
+
+E un esempio di fence eseguibile col PyRunner:
+
+```py live
+nomi = ["Luca", "Anna", "Marco"]
+for n in nomi:
+    print(f"Ciao, {n}!")
+```
+:::
+
+:::cleancode
+Questi sono consigli su come scrivere e organizzare in modo efficace il codice.
+:::
+
+:::nutshell
+- Questo callout contiene un elenco puntato dei concetti chiave visti nella lezione
+- Per poter comparire nell'indice, il titolo è un H1
+:::
+
+:::mindmap
+Questo blocco contiene il codice mermaid di una mappa mentale. Per ora è solo il contenitore — l'integrazione mermaid arriverà in un PR separato.
+:::
+
+## Tipi default ristilizzati (4)
+
+:::info
+Queste sono generiche informazioni utili sulla programmazione o sull'informatica in generale.
+:::
+
+:::tip
+Un consiglio mirato. Equivalente all'uso storico di `:::tip[Ricorda che]`.
+:::
+
+:::warning
+Queste sono avvertenze su qualcosa in cui bisogna fare molta attenzione per evitare di commettere errori.
+:::
+
+:::danger
+Escalation più severa: errori che bloccano del tutto l'esecuzione o causano comportamenti imprevisti gravi.
+:::
+
+## Override del titolo
+
+Tutti i callout accettano un titolo custom con la sintassi `:::tipo[Titolo]`.
+
+:::prereq[Conoscenze richieste]
+Esempio con titolo override.
+:::
+
+:::warning[Salvare il valore restituito]
+Esempio retro-compatibile con i `.mdx` esistenti.
+:::
+
+## Fallback (tipo `note`, senza icona)
+
+:::note
+Tenuto come fallback minimale per `:::note`. Non ha icona dedicata (nessun PNG in `static/img/callouts/`).
+:::

docusaurus.config.ts

@@ -5,6 +5,23 @@ import type * as Preset from '@docusaurus/preset-classic';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const remarkPyRunner = require('./plugins/pyrunner/remark.js');
 
+// Keyword admonition custom (Notion-style callouts). Vedi
+// src/theme/Admonition/index.tsx per il registry di titoli + icone PNG.
+const admonitions = {
+  keywords: [
+    'prereq',
+    'learn',
+    'exercise',
+    'definition',
+    'history',
+    'code',
+    'cleancode',
+    'nutshell',
+    'mindmap',
+  ],
+  extendDefaults: true,
+};
+
 const config: Config = {
   title: 'Python Doesn\'t Byte',
   tagline: 'Il libro di testo, reinventato.',
@@ -49,6 +66,7 @@ const config: Config = {
           // Remove this to remove the "edit this page" links.
           editUrl: 'https://github.com/marcofarina/python-doesnt-byte',
           beforeDefaultRemarkPlugins: [remarkPyRunner],
+          admonitions,
         },
         blog: {
           showReadingTime: true,
@@ -92,6 +110,7 @@ const config: Config = {
         sidebarPath: './sidebars/programmatore.ts',
         editUrl: 'https://github.com/marcofarina/python-doesnt-byte',
         beforeDefaultRemarkPlugins: [remarkPyRunner],
+        admonitions,
       },
     ],
     [
@@ -103,6 +122,7 @@ const config: Config = {
         sidebarPath: './sidebars/artefice.ts',
         editUrl: 'https://github.com/marcofarina/python-doesnt-byte',
         beforeDefaultRemarkPlugins: [remarkPyRunner],
+        admonitions,
       },
     ],
     [
@@ -114,6 +134,7 @@ const config: Config = {
         sidebarPath: './sidebars/archivista.ts',
         editUrl: 'https://github.com/marcofarina/python-doesnt-byte',
         beforeDefaultRemarkPlugins: [remarkPyRunner],
+        admonitions,
       },
     ],
     [
@@ -125,6 +146,7 @@ const config: Config = {
         sidebarPath: './sidebars/apprendista.ts',
         editUrl: 'https://github.com/marcofarina/python-doesnt-byte',
         beforeDefaultRemarkPlugins: [remarkPyRunner],
+        admonitions,
       },
     ],
   ],

src/css/custom.css

@@ -808,4 +808,149 @@ main [class*='generatedIndexPage'] > p {
   line-height: 1.6;
   color: var(--at-fg-body);
   max-width: 72ch;
-}
+}
+
+/* ─────────────── Notion-style callouts (admonition swizzle) ───────────────
+   Palette per tipo: --callout-<tipo>-bg (sfondo blocco) e
+   --callout-<tipo>-fg (titolo). I PNG sono multicolore: niente tint.
+   Light/dark gestiti via override delle variabili sotto [data-theme='dark'].
+*/
+
+:root {
+  --callout-prereq-bg:     oklch(96% 0.025 240);
+  --callout-prereq-fg:     oklch(48% 0.16 240);
+  --callout-learn-bg:      oklch(96% 0.025 350);
+  --callout-learn-fg:      oklch(52% 0.18 350);
+  --callout-exercise-bg:   oklch(95% 0.03 320);
+  --callout-exercise-fg:   oklch(52% 0.2 320);
+  --callout-definition-bg: oklch(95% 0.04 70);
+  --callout-definition-fg: oklch(48% 0.13 70);
+  --callout-history-bg:    oklch(94% 0.045 35);
+  --callout-history-fg:    oklch(48% 0.16 35);
+  --callout-code-bg:       oklch(95% 0 0);
+  --callout-code-fg:       oklch(40% 0 0);
+  --callout-cleancode-bg:  oklch(95% 0.025 270);
+  --callout-cleancode-fg:  oklch(48% 0.18 270);
+  --callout-nutshell-bg:   oklch(95% 0.03 55);
+  --callout-nutshell-fg:   oklch(46% 0.09 55);
+  --callout-mindmap-bg:    oklch(95% 0.04 175);
+  --callout-mindmap-fg:    oklch(46% 0.13 175);
+  --callout-info-bg:       oklch(95% 0.04 145);
+  --callout-info-fg:       oklch(46% 0.14 145);
+  --callout-tip-bg:        oklch(96% 0.05 90);
+  --callout-tip-fg:        oklch(52% 0.15 85);
+  --callout-warning-bg:    oklch(94% 0.05 55);
+  --callout-warning-fg:    oklch(56% 0.17 50);
+  --callout-danger-bg:     oklch(93% 0.04 15);
+  --callout-danger-fg:     oklch(48% 0.22 18);
+  --callout-note-bg:       oklch(95% 0 0);
+  --callout-note-fg:       oklch(45% 0 0);
+}
+
+[data-theme='dark'] {
+  --callout-prereq-bg:     oklch(26% 0.04 245);
+  --callout-prereq-fg:     oklch(78% 0.12 240);
+  --callout-learn-bg:      oklch(27% 0.05 350);
+  --callout-learn-fg:      oklch(82% 0.11 350);
+  --callout-exercise-bg:   oklch(26% 0.06 320);
+  --callout-exercise-fg:   oklch(80% 0.14 320);
+  --callout-definition-bg: oklch(26% 0.045 70);
+  --callout-definition-fg: oklch(82% 0.1 70);
+  --callout-history-bg:    oklch(26% 0.06 35);
+  --callout-history-fg:    oklch(78% 0.13 35);
+  --callout-code-bg:       oklch(28% 0 0);
+  --callout-code-fg:       oklch(82% 0 0);
+  --callout-cleancode-bg:  oklch(26% 0.05 270);
+  --callout-cleancode-fg:  oklch(80% 0.13 270);
+  --callout-nutshell-bg:   oklch(26% 0.035 55);
+  --callout-nutshell-fg:   oklch(80% 0.07 55);
+  --callout-mindmap-bg:    oklch(26% 0.05 175);
+  --callout-mindmap-fg:    oklch(80% 0.12 175);
+  --callout-info-bg:       oklch(26% 0.05 145);
+  --callout-info-fg:       oklch(82% 0.13 145);
+  --callout-tip-bg:        oklch(27% 0.05 90);
+  --callout-tip-fg:        oklch(85% 0.13 90);
+  --callout-warning-bg:    oklch(27% 0.08 55);
+  --callout-warning-fg:    oklch(82% 0.15 50);
+  --callout-danger-bg:     oklch(28% 0.08 15);
+  --callout-danger-fg:     oklch(78% 0.18 18);
+  --callout-note-bg:       oklch(26% 0 0);
+  --callout-note-fg:       oklch(78% 0 0);
+}
+
+.callout {
+  border-radius: 10px;
+  padding: 16px 20px;
+  margin: 1.25rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  color: var(--ifm-font-color-base);
+}
+
+.callout__header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.callout__icon {
+  width: auto;
+  height: auto;
+  max-width: 30px;
+  max-height: 30px;
+  flex-shrink: 0;
+  display: block;
+}
+
+.callout .callout__title {
+  margin: 0;
+  padding: 0;
+  font-weight: 700;
+  font-size: 1.5rem;
+  line-height: 1;
+}
+
+.callout .callout__body {
+  line-height: 1.4;
+}
+
+.callout__body > :last-child {
+  margin-bottom: 0;
+}
+
+.callout__body ul,
+.callout__body ol {
+  margin: 0.25rem 0 0;
+  padding-left: 1.25rem;
+}
+
+/* Mapping tipo → bg + fg titolo. L'icona PNG ha colore proprio. */
+.callout--prereq     { background: var(--callout-prereq-bg); }
+.callout--prereq     .callout__title { color: var(--callout-prereq-fg); }
+.callout--learn      { background: var(--callout-learn-bg); }
+.callout--learn      .callout__title { color: var(--callout-learn-fg); }
+.callout--exercise   { background: var(--callout-exercise-bg); }
+.callout--exercise   .callout__title { color: var(--callout-exercise-fg); }
+.callout--definition { background: var(--callout-definition-bg); }
+.callout--definition .callout__title { color: var(--callout-definition-fg); }
+.callout--history    { background: var(--callout-history-bg); }
+.callout--history    .callout__title { color: var(--callout-history-fg); }
+.callout--code       { background: var(--callout-code-bg); }
+.callout--code       .callout__title { color: var(--callout-code-fg); }
+.callout--cleancode  { background: var(--callout-cleancode-bg); }
+.callout--cleancode  .callout__title { color: var(--callout-cleancode-fg); }
+.callout--nutshell   { background: var(--callout-nutshell-bg); }
+.callout--nutshell   .callout__title { color: var(--callout-nutshell-fg); }
+.callout--mindmap    { background: var(--callout-mindmap-bg); }
+.callout--mindmap    .callout__title { color: var(--callout-mindmap-fg); }
+.callout--info       { background: var(--callout-info-bg); }
+.callout--info       .callout__title { color: var(--callout-info-fg); }
+.callout--tip        { background: var(--callout-tip-bg); }
+.callout--tip        .callout__title { color: var(--callout-tip-fg); }
+.callout--warning    { background: var(--callout-warning-bg); }
+.callout--warning    .callout__title { color: var(--callout-warning-fg); }
+.callout--danger     { background: var(--callout-danger-bg); }
+.callout--danger     .callout__title { color: var(--callout-danger-fg); }
+.callout--note       { background: var(--callout-note-bg); }
+.callout--note       .callout__title { color: var(--callout-note-fg); }

src/theme/Admonition/index.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from 'react';
+import clsx from 'clsx';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+interface CalloutEntry {
+  defaultTitle: string;
+  icon: string | null;
+}
+
+const CALLOUT_REGISTRY: Record<string, CalloutEntry> = {
+  prereq: { defaultTitle: 'Prerequisiti', icon: 'prereq.png' },
+  learn: {
+    defaultTitle: 'Cosa imparerai in questa lezione',
+    icon: 'learn.png',
+  },
+  exercise: {
+    defaultTitle: 'Cosa imparerai con questo esercizio',
+    icon: 'exercise.png',
+  },
+  definition: { defaultTitle: 'Definizioni', icon: 'definition.png' },
+  history: { defaultTitle: 'Cenni storici', icon: 'history.png' },
+  code: { defaultTitle: 'Programmazione', icon: 'code.png' },
+  cleancode: { defaultTitle: 'Clean code', icon: 'cleancode.png' },
+  nutshell: { defaultTitle: 'In a nutshell', icon: 'nutshell.png' },
+  mindmap: { defaultTitle: 'Mindmap', icon: 'mindmap.png' },
+  info: { defaultTitle: 'Informazioni utili', icon: 'info.png' },
+  tip: { defaultTitle: 'Suggerimento', icon: 'tip.png' },
+  warning: { defaultTitle: 'Attenzione', icon: 'warning.png' },
+  danger: { defaultTitle: 'Pericolo', icon: 'danger.png' },
+  note: { defaultTitle: 'Nota', icon: null },
+};
+
+interface AdmonitionProps {
+  type: string;
+  title?: ReactNode;
+  icon?: ReactNode;
+  children: ReactNode;
+}
+
+export default function Admonition(props: AdmonitionProps): ReactNode {
+  const { type, title, children } = props;
+  const entry = CALLOUT_REGISTRY[type] ?? CALLOUT_REGISTRY.note;
+  const iconUrl = useBaseUrl(entry.icon ? `/img/callouts/${entry.icon}` : '');
+
+  return (
+    <aside className={clsx('callout', `callout--${type}`)}>
+      <div className="callout__header">
+        {entry.icon && (
+          <img
+            src={iconUrl}
+            alt=""
+            aria-hidden="true"
+            className="callout__icon"
+          />
+        )}
+        <h4 className="callout__title">{title ?? entry.defaultTitle}</h4>
+      </div>
+      <div className="callout__body">{children}</div>
+    </aside>
+  );
+}