Calendar¶
Extensió de Pymdownx Blocks que renderitza calendaris a partir d'una configuració TOML embeguda dins d'un bloc /// calendar. Suporta dies festius, rangs amb classes CSS, anotacions per dia, tooltips i localització.
Configuració¶
Afegeix l'extensió a markdown_extensions dins de properdocs.yml:
| Opció | Tipus | Per defecte | Descripció |
|---|---|---|---|
locale |
string | "en" |
Codi de llengua per defecte aplicat als blocs que no en defineixen un. Valor especial "auto" per agafar l'idioma de la pàgina (vegeu Localització). |
L'extensió activa automàticament el gestor de blocs de pymdownx; els estils ja venen inclosos al tema.
Sintaxi¶
El cos del bloc és TOML; les dates es declaren com a local-date (YYYY-MM-DD).
| Camp | Tipus | Per defecte | Descripció |
|---|---|---|---|
start |
data | obligatori | Primer dia del període. |
end |
data | obligatori | Últim dia (inclusiu, >= start). |
weekends |
"show" | "plain" | "hide" |
"show" |
Tractament de dissabtes i diumenges. |
size |
"sm" | "md" | "lg" | "xl" | "xxl" |
"lg" |
Mida del calendari, de més petit a més gran. Vegeu Mida. |
locale |
string | hereta | Codi de llengua. |
month_names |
llista de 12 strings | — | Noms de mes personalitzats. |
weekday_labels |
llista de 7 strings | — | Noms de dia personalitzats. |
[holiday] |
taula | — | Configuració de festius (dates, plain, tooltip). Veure Festius. |
ranges |
array of tables | [] |
Rangs amb classe i tooltip. |
days |
array of tables | [] |
Anotacions per dia individual. |
Festius¶
Els festius es configuren dins d'una taula [holiday]:
| Camp | Tipus | Per defecte | Descripció |
|---|---|---|---|
dates |
llista de dates / parells [from, to] |
[] |
Llista barrejada de dates simples i rangs. Tots els dies expandits reben la classe holiday. |
plain |
booleà | false |
Si true, les classes/tooltips de [[ranges]] no s'apliquen sobre festius. |
tooltip |
string | "" |
Text de tooltip aplicat a cada dia festiu. |
/// calendar
start = 2026-04-01
end = 2026-04-30
[holiday]
plain = true
tooltip = "Festiu"
dates = [
2026-04-25,
[2026-04-02, 2026-04-06],
]
[[ranges]]
from = 2026-04-01
to = 2026-04-15
class = "blue"
tooltip = "Sprint Q2"
///
Rangs¶
Cada [[ranges]] aplica una classe CSS (i opcionalment un tooltip) a un interval inclusiu.
| Camp | Tipus | Descripció |
|---|---|---|
from |
data | Inici (inclusiu). |
to |
data | Final (inclusiu, >= from). |
class |
string | Classe CSS aplicada a cada dia. |
tooltip |
string (opc.) | Text de tooltip (Markdown) repetit a cada dia del rang. |
label |
string (opc.) | Etiqueta curta repetida a cada dia del rang. |
exclude |
llista de "weekends" | "holidays" (opc.) |
Dies que no reben la classe/tooltip/etiqueta d'aquest rang. Per defecte [] (cap dia exclòs). |
Quan diversos rangs es solapen, totes les classes s'apliquen i els tooltips es combinen en un mateix popover amb un punt per font.
/// calendar
start = 2026-02-01
end = 2026-02-28
[[ranges]]
from = 2026-02-02
to = 2026-02-13
class = "blue"
tooltip = "Sprint A"
[[ranges]]
from = 2026-02-09
to = 2026-02-20
class = "green"
tooltip = "Suport sprint"
///
Excloure caps de setmana i festius¶
exclude fa que els tipus de dia indicats, dins del rang, no rebin la classe, el tooltip ni l'etiqueta d'aquest rang. Afecta només aquest rang, a diferència de weekends = "plain" i [holiday].plain, que són globals per a tot el calendari.
/// calendar
start = 2026-02-01
end = 2026-02-28
[holiday]
dates = [2026-02-14]
[[ranges]]
from = 2026-02-02
to = 2026-02-20
class = "blue"
tooltip = "Sprint (dies laborables)"
exclude = ["weekends", "holidays"]
///
Anotacions per dia¶
[[days]] afegeix classe i/o tooltip a un dia concret sense haver de declarar un [[ranges]] d'un sol dia:
| Camp | Tipus | Obligatori | Descripció |
|---|---|---|---|
date |
data | sí | Dia que rep l'anotació. |
class |
string | no | Classe CSS afegida a la cel·la. |
tooltip |
string | no | Text de tooltip (Markdown). |
label |
string | no | Etiqueta curta visible a la cantonada de la cel·la. Pintat amb la classe del class. |
override |
booleà | no (per defecte false) |
Si true, substitueix la classe, el tooltip i l'etiqueta que el dia rebria d'un cap de setmana, festiu o [[ranges]] per les d'aquesta anotació, en lloc de sumar-s'hi. |
Les anotacions per dia s'apliquen sempre, també sobre festius i caps de setmana en mode plain.
/// calendar
start = 2026-03-01
end = 2026-03-31
[[days]]
date = 2026-03-09
class = "purple"
tooltip = "Demo stakeholders"
[[days]]
date = 2026-03-23
label = "R"
tooltip = "Recordatori: informe"
///
Substituir un rang o festiu del tot¶
Per defecte, la classe, el tooltip i l'etiqueta d'una anotació de dia se sumen als que ja tingués el dia (per exemple, un dia dins d'un rang). Amb override = true, els substitueixen del tot en comptes de sumar-s'hi — útil per marcar una excepció puntual dins d'un rang o festiu.
/// calendar
start = 2026-01-01
end = 2026-01-31
[[ranges]]
from = 2026-01-10
to = 2026-01-20
class = "sprint"
tooltip = "Sprint"
[[days]]
date = 2026-01-15
class = "holiday"
tooltip = "Dia lliure excepcional"
override = true
///
Tooltips¶
Cada [[ranges]], [[days]] i [holiday].tooltip admet Markdown complet: negretes, links, codi inline, etc. El tooltip s'obre passant el ratolí per sobre del dia o donant-li focus per teclat.
Quan diversos rangs/anotacions toquen el mateix dia, totes les cadenes s'apilen com a paràgrafs separats dins el mateix tooltip.
Cap configuració extra al properdocs.yml: ni attr_list, ni content.tooltips, ni cap altre afegit. Tot ja ve cobert pel tema.
/// calendar
start = 2026-02-01
end = 2026-02-28
[holiday]
tooltip = "Festiu *nacional* — `oficina tancada`"
dates = [2026-02-14]
[[ranges]]
from = 2026-02-09
to = 2026-02-13
class = "blue"
tooltip = "Sprint **12** — feature freeze el [divendres](https://example.org)"
[[days]]
date = 2026-02-20
class = "purple"
tooltip = "Demo amb stakeholders. Recordeu portar el `prototype.zip`."
///
oficina tancadaprototype.zip.Passa el ratolí (o pitja Tab) sobre els dies acolorits per veure el contingut formatat.
Caps de setmana¶
| Mode | Cel·les Sat/Sun | Classe weekend |
Classes de [[ranges]] |
Columnes |
|---|---|---|---|---|
show (per defecte) |
sí | sí | sí | 7 |
plain |
sí | sí | no | 7 |
hide |
no | — | n/a | 5 |
Mode plain deixa Sat/Sun sense la classe del rang (útil per a sprints Dl–Dv):
/// calendar
start = 2026-01-01
end = 2026-01-31
weekends = "plain"
[[ranges]]
from = 2026-01-05
to = 2026-01-30
class = "blue"
tooltip = "Sprint laboral"
///
Mode hide retalla la graella a 5 columnes:
Mida¶
| Valor | Descripció |
|---|---|
"xxl" |
La mida més gran. |
"xl" |
Una mica més petit que "xxl". |
"lg" |
Mida per defecte del calendari. |
"md" |
Més petit que "lg". |
"sm" |
La mida més petita, per a encabir-ne molts junts en poc espai. |
Com més petita la mida, més mesos hi caben per fila (útil, per exemple, a una guia de curs on cal mostrar el calendari al costat d'una taula d'unitats):
/// calendar
start = 2026-01-01
end = 2026-02-28
size = "sm"
[[ranges]]
from = 2026-01-05
to = 2026-01-16
class = "blue"
tooltip = "Període d'exàmens"
///
Localització¶
Locales empaquetats: en, ca, es, fr, de, pt, it, gl, eu. Precedència: month_names / weekday_labels inline > camp locale > opció de l'extensió > anglès.
locale: auto¶
Si el lloc usa el plugin mkdocs-static-i18n (o l'integració d'i18n de Material), pots configurar locale: auto a l'extensió i cada calendari hereta l'idioma de la pàgina:
Quan no hi ha context de pàgina (p. ex. tests aïllats), auto cau a anglès.
Sobreescriptura puntual:
locale = "ca"
month_names = ["Gen","Feb","Mar","Abr","Mai","Jun","Jul","Ago","Set","Oct","Nov","Des"]
weekday_labels = ["L","M","X","J","V","S","D"]
Si tens babel instal·lat, qualsevol codi que reconega Babel (per exemple nl_NL) es resol automàticament.
Inclusió de fitxers (!include)¶
Per compartir festius o rangs entre diversos calendaris (sprints d'equip, calendari escolar comú, etc.) pots extreure'ls a un fitxer TOML i incloure'l amb !include "ruta":
[holiday]
plain = true
tooltip = "Festiu"
dates = [
2026-01-01,
2026-01-06,
[2026-04-02, 2026-04-06],
2026-12-25,
]
/// calendar
start = 2026-01-01
end = 2026-12-31
weekends = "hide"
!include "data/festius_2026.toml"
///
Notes:
- La ruta és relativa al fitxer Markdown que conté el bloc.
- Els includes poden anidar-se (un fitxer inclòs pot incloure'n d'altres) fins a 16 nivells; els cicles es detecten i emeten un error.
- La directiva ha d'aparèixer sola en una línia.
!includeenmig d'una línia es deixa intacte. - El fitxer inclòs es concatena textualment abans de parsejar el TOML; ha de ser TOML vàlid en el seu lloc.
Colors disponibles¶
8 classes de color preestablertes per class a ranges o days. Light/dark mode automàtic.
| Classe | Mostra | Variables CSS |
|---|---|---|
red |
Aa | --md-cal-hue-red-bg / -fg |
orange |
Aa | --md-cal-hue-orange-bg / -fg |
yellow |
Aa | --md-cal-hue-yellow-bg / -fg |
green |
Aa | --md-cal-hue-green-bg / -fg |
teal |
Aa | --md-cal-hue-teal-bg / -fg |
blue |
Aa | --md-cal-hue-blue-bg / -fg |
purple |
Aa | --md-cal-hue-purple-bg / -fg |
pink |
Aa | --md-cal-hue-pink-bg / -fg |
Sobreescriu les variables a extra.css per retunejar el to.
/// calendar
start = 2026-05-01
end = 2026-05-31
weekends = "plain"
[[ranges]]
from = 2026-05-04
to = 2026-05-08
class = "red"
[[ranges]]
from = 2026-05-11
to = 2026-05-15
class = "orange"
[[ranges]]
from = 2026-05-18
to = 2026-05-22
class = "yellow"
[[ranges]]
from = 2026-05-25
to = 2026-05-29
class = "green"
///
Estils¶
Per afinar mides o colors sense modificar el tema, sobreescriu les variables CSS al teu extra_css:
Variables disponibles: --md-cal-cell-size, --md-cal-gap, --md-cal-bg, --md-cal-fg, --md-cal-border, --md-cal-muted, --md-cal-weekend, --md-cal-holiday, --md-cal-out, més la paleta --md-cal-hue-*-bg/fg.
Errors¶
Quan la configuració és invàlida, l'extensió emet un missatge llegible en lloc de fer caure la build:
Calendar error: 'end' (2026-01-01) must be on or after 'start' (2026-02-01)