diff --git a/docs/callouts-demo.mdx b/docs/callouts-demo.mdx new file mode 100644 index 0000000..c1bd013 --- /dev/null +++ b/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/`). +::: diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c72ad8a..44e027c 100644 --- a/docusaurus.config.ts +++ b/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, }, ], ], diff --git a/src/css/custom.css b/src/css/custom.css index 4b2da60..515bf37 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -808,4 +808,149 @@ main [class*='generatedIndexPage'] > p { line-height: 1.6; color: var(--at-fg-body); max-width: 72ch; -} \ No newline at end of file +} + +/* ─────────────── Notion-style callouts (admonition swizzle) ─────────────── + Palette per tipo: --callout--bg (sfondo blocco) e + --callout--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); } \ No newline at end of file diff --git a/src/theme/Admonition/index.tsx b/src/theme/Admonition/index.tsx new file mode 100644 index 0000000..82b5143 --- /dev/null +++ b/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 = { + 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 ( + + ); +} diff --git a/static/img/callouts/.gitkeep b/static/img/callouts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/static/img/callouts/cleancode.png b/static/img/callouts/cleancode.png new file mode 100644 index 0000000..3ecacc0 Binary files /dev/null and b/static/img/callouts/cleancode.png differ diff --git a/static/img/callouts/code.png b/static/img/callouts/code.png new file mode 100644 index 0000000..6533b6e Binary files /dev/null and b/static/img/callouts/code.png differ diff --git a/static/img/callouts/danger.png b/static/img/callouts/danger.png new file mode 100644 index 0000000..6301202 Binary files /dev/null and b/static/img/callouts/danger.png differ diff --git a/static/img/callouts/definition.png b/static/img/callouts/definition.png new file mode 100644 index 0000000..29afe46 Binary files /dev/null and b/static/img/callouts/definition.png differ diff --git a/static/img/callouts/exercise.png b/static/img/callouts/exercise.png new file mode 100644 index 0000000..920e961 Binary files /dev/null and b/static/img/callouts/exercise.png differ diff --git a/static/img/callouts/history.png b/static/img/callouts/history.png new file mode 100644 index 0000000..3bf6367 Binary files /dev/null and b/static/img/callouts/history.png differ diff --git a/static/img/callouts/info.png b/static/img/callouts/info.png new file mode 100644 index 0000000..f1c8cd0 Binary files /dev/null and b/static/img/callouts/info.png differ diff --git a/static/img/callouts/learn.png b/static/img/callouts/learn.png new file mode 100644 index 0000000..920e961 Binary files /dev/null and b/static/img/callouts/learn.png differ diff --git a/static/img/callouts/mindmap.png b/static/img/callouts/mindmap.png new file mode 100644 index 0000000..3226c54 Binary files /dev/null and b/static/img/callouts/mindmap.png differ diff --git a/static/img/callouts/nutshell.png b/static/img/callouts/nutshell.png new file mode 100644 index 0000000..0ea8f4a Binary files /dev/null and b/static/img/callouts/nutshell.png differ diff --git a/static/img/callouts/prereq.png b/static/img/callouts/prereq.png new file mode 100644 index 0000000..6dc58d4 Binary files /dev/null and b/static/img/callouts/prereq.png differ diff --git a/static/img/callouts/tip.png b/static/img/callouts/tip.png new file mode 100644 index 0000000..34a863b Binary files /dev/null and b/static/img/callouts/tip.png differ diff --git a/static/img/callouts/warning.png b/static/img/callouts/warning.png new file mode 100644 index 0000000..d9bc4fa Binary files /dev/null and b/static/img/callouts/warning.png differ