bib2graph/mkdocs.yml at dev · complexluise/bib2graph · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# mkdocs.yml — sitio de documentación de bib2graph
#
# Fuente: docs/ (mismo árbol que ya mantenemos). El sitio NO duplica contenido:
# reusa API.md, ARCHITECTURE.md, los ADRs (docs/decisiones/) y, vía
# include-markdown, los .md de la raíz (CONTRIBUTING, CHANGELOG, AI_DISCLOSURE).
# Lo interno (Notas/, _archivo/, features/, ROADMAP/, borradores) queda fuera del
# sitio público — ver `exclude_docs` más abajo.
#
# Build local:   uv sync --group docs && uv run mkdocs serve
# Deploy:        .github/workflows/docs.yml → GitHub Pages (push a main)

site_name: bib2graph
site_description: >-
  De una búsqueda bibliográfica a redes de citación reproducibles — una
  biblioteca de literatura que curás vos, sin servidores ni planillas.
site_author: Equipo bib2graph
site_url: https://complexluise.github.io/bib2graph/
copyright: Copyright &copy; 2026 Equipo bib2graph (complexluise) — GPL-3.0-or-later

repo_url: https://github.com/complexluise/bib2graph
repo_name: complexluise/bib2graph
edit_uri: edit/dev/docs/

docs_dir: docs

# Validación de enlaces. Muchos .md fuente —los ADRs (inmutables) y los archivos
# de raíz como CONTRIBUTING/VERSIONING/AGENTS— enlazan entre sí con rutas
# relativas que son correctas en GitHub (su render principal) pero caen fuera de
# docs/ en el sitio. Los degradamos a `info` para no ahogar el build con ruido
# intencional, PERO mantenemos `anchors: warn` para seguir cazando anclas rotas
# reales en las páginas que sí escribimos.
validation:
  links:
    not_found: info
    anchors: warn
    absolute_links: ignore
    unrecognized_links: ignore

theme:
  name: material
  language: es
  icon:
    repo: fontawesome/brands/github
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: teal
      accent: deep orange
      toggle:
        icon: material/weather-night
        name: Cambiar a modo oscuro
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: deep orange
      toggle:
        icon: material/weather-sunny
        name: Cambiar a modo claro
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - navigation.instant
    - navigation.tracking
    - navigation.indexes
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.action.edit

plugins:
  - search:
      lang: es
  - include-markdown
  # Anima sesiones de terminal: bloques precedidos por <!-- termynal -->.
  - termynal
  # Referencia de la librería autogenerada desde los docstrings (src layout).
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            show_root_heading: true
            show_root_full_path: false
            show_source: false
            show_signature_annotations: true
            separate_signature: true
            members_order: source
            heading_level: 2
            filters: ["!^_"]

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - tables
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  # Referencia del CLI b2g autogenerada desde el grupo Click.
  - mkdocs-click

# Páginas que se construyen y son enlazables por URL, pero NO aparecen en el
# sidebar. Las 38 ADRs viven en su índice docs/decisiones/README.md (visible
# por URL — ejercicio de transferencia — pero no en el nav principal, para no
# abrumar al usuario final ni al asistente de IA).
not_in_nav: |
  /decisiones/0*.md
  /decisiones/registro-ia.md

# Contenido interno: no se publica en el sitio. Si algo de acá hay que mostrar,
# se promueve explícitamente a una página del nav.
exclude_docs: |
  Notas/
  _archivo/
  features/
  ROADMAP/
  RELEASE_TEMPLATE.md

# Estructura Diátaxis (https://diataxis.fr): Inicio (aprender/empezar, camino
# recomendado = asistente de IA — incluye el único tutorial), Guías (resolver
# una tarea), Referencia (consultar). La Explicación (entender: arquitectura,
# ADRs, PRD) vive dentro de "Contribuye" — es contexto para quien va a tocar
# el código, no una sección aparte.
nav:
  - Inicio:
      - index.md
      - Instalación: getting-started/installation.md
      - Quickstart: getting-started/quickstart.md
      - Tu primer mapa (5 min): tutoriales/primer-mapa.md
  - Guías (how-to):
      - guias/index.md
      - Ecuación de búsqueda: guias/ecuacion-busqueda.md
      - Forrajeo (expandir el corpus): guias/forrajeo.md
      - Curación PRISMA: guias/curacion-prisma.md
      - Leer las 5 redes: guias/leer-redes.md
      - Del corpus al reporte: guias/reporte.md
  - Referencia:
      - API de Python: reference/python-api.md
      - CLI b2g: reference/cli.md
      - Glosario: reference/glosario.md
  - Contribuye:
      - Contribuir: contributing.md
      - Arquitectura: ARCHITECTURE.md
      - Requisitos del producto (PRD): PRD.md
      - Versionado: versioning.md
      - IA en el desarrollo: ai-disclosure.md
      - Changelog: changelog.md