create-ngx-docs-site

Scaffolding para crear un sitio de documentacion en Angular basado en Markdown:

npm create ngx-docs-site mi-sitio
cd mi-sitio
npm install
npm start

Genera un proyecto Angular (standalone + signals) sobre @ngx-docs-markdown-kit/parser-md, con Angular Material + Tailwind CSS como base del template (no son opcionales: el sitio depende de ambas librerias desde el inicio). Sin scope a proposito (sigue la convencion create-* de npm create, igual que create-vite/create-astro).

npm start levanta un servidor de desarrollo con recarga en caliente (ng serve) en http://localhost:4200 -- cualquier cambio en public/content-parser-md/**/*.md o en el codigo fuente se refleja solo, sin reiniciar nada a mano.

No incluye Docker -- eso queda a criterio de quien use la plantilla.

Flags de npm create ngx-docs-site <nombre> [flags...]

Todos los flags van despues de -- (convencion de npm create):

npm create ngx-docs-site mi-sitio -- --no-image --render-mode=server

Extensiones opcionales (--no-<id>)

Por default se instala TODO -- incluidas las extensiones opcionales del ecosistema. Para omitir alguna:

| id | Paquete | Que agrega | | --- | --- | --- | | image | @ngx-docs-markdown-kit/parser-md-image | Fences ```image con align/width/description/styles (sin esta extension, un ![alt](url) normal sigue funcionando). | | code-block-themes | @ngx-docs-markdown-kit/parser-md-code-block-themes | ~80 paletas de color reales para el selector "Mod" de los bloques de codigo. | | card | @ngx-docs-markdown-kit/parser-md-card | Fences ```content-card -- tarjeta de contenido general con <mat-card> real de Angular Material (imagen/titulo/subtitulo/contenido/acciones). |

Un --no-<id> desconocido no falla la generacion -- se avisa como flag no reconocida (probable typo) y el sitio se crea igual. Instalar una extension mas adelante, sobre un sitio ya generado, tambien es valido: npm install @ngx-docs-markdown-kit/parser-md-image y seguir su README para terminar de conectarla (import + .use() + imports del componente).

Modo de render (--render-mode=<static|server>)

Elige, en build-time, como se sirve el sitio en produccion (npm run build) -- no afecta en absoluto a npm start/desarrollo, que siempre es un dev server con recarga en caliente sin importar este flag.

• static (default -- no hace falta pasar el flag) -- SSG/prerender puro: npm run build genera solo archivos estaticos (dist/mi-sitio/browser/, un index.html real por pagina, sin ninguna carpeta de servidor). En produccion no corre ningun proceso Node.js -- se sirve con cualquier hosting estatico (nginx, un CDN, GitHub Pages, Netlify, etc.), igual que cualquier sitio HTML/CSS/JS plano. Recomendado para documentacion: todo el contenido sale de Markdown, conocido por completo al momento de compilar, no hay ningun dato realmente dinamico que justifique un servidor corriendo.
• server -- SSR completo (@angular/ssr): npm run build genera ademas dist/mi-sitio/server/server.mjs, un servidor Express real que hay que dejar corriendo en produccion (node dist/mi-sitio/server/server.mjs, variable de entorno PORT). Uselo solo si en algun momento el sitio necesita contenido genuinamente dinamico por request (algo que este template, tal cual viene, no tiene -- ni siquiera en modo server el contenido cambia entre requests, ya que el manifiesto de Markdown se conoce en build-time igual).

Por que un cambio de contenido siempre requiere reconstruir, en los 2 modos -- no es una limitacion nueva de static: app.routes.server.ts ya marca todas las rutas del sitio como prerenderizables (RenderMode.Prerender), asi que el HTML de cada pagina se genera una sola vez, en npm run build, sin importar el modo de render elegido. Si editas un .md de public/content-parser-md/, el cambio recien aparece en produccion despues de volver a correr npm run build (y, si corresponde, redeploy). Durante desarrollo (npm start) esto no aplica -- el dev server sirve el contenido en vivo, sin ningun paso de build de por medio.

Migrar un sitio ya generado de un modo a otro es manual (no hay un comando para esto sobre un sitio existente): editar outputMode/ssr en angular.json (ver @angular/build, opcion outputMode del builder application) y ajustar package.json (sacar/agregar express/@types/express y el script serve:ssr:<nombre> segun corresponda).

Build y despliegue

npm run build

Corre el generador del manifiesto de contenido + generate-seo-files.mjs (sitemap.xml/robots.txt reales) + ng build. Que queda en dist/mi-sitio/ depende del modo de render:

• static: solo dist/mi-sitio/browser/ -- subi ese directorio tal cual a cualquier hosting estatico (nginx, Netlify, Cloudflare Pages, GitHub Pages, un bucket S3+CDN, etc.). No hace falta Node.js corriendo en el servidor de destino, ni ningun proceso -- son archivos estaticos.
• server: dist/mi-sitio/browser/ + dist/mi-sitio/server/server.mjs -- el servidor real corre con:

  PORT=4000 node dist/mi-sitio/server/server.mjs

  Requiere Node.js instalado en el servidor de destino y un proceso corriendo permanentemente (systemd, PM2, un contenedor, etc.).

Configuracion (src/app/core/ + frugocorp_modules/)

Cada sitio generado trae su config (mostrar/ocultar barras, nombre/logo, description/keywords/siteUrl por default de SEO, alineacion default de imagenes, lenguajes visibles del selector de temas) como constantes TypeScript compiladas dentro del bundle. DESIGN_CONFIG/RESOURCES_CONFIG (nada de una libreria en particular) viven sueltas en src/app/core/; el config de cada libreria FrugoCorp (SEO_CONFIG/IMAGE_CONFIG/CODE_BLOCK_THEMES_CONFIG/CODE_BLOCK_COLORS_CONFIG) vive en frugocorp_modules/<paquete>/config/ -- en la RAIZ del sitio (hermano de src/, no anidado adentro), una carpeta por paquete (parser-md-seo/parser-md-image/parser-md-code-block-themes/parser-md-code-block), para que core/ no se llene de archivos sueltos de distintas librerias a medida que el sitio crece (cada carpeta de paquete tambien trae su propia components/, vacia por default, para componentes propios que envuelvan/extiendan esa libreria si algun dia hacen falta). Cambiar cualquiera de estos valores es editar el archivo y recompilar el sitio -- no un JSON en public/ pedido por HttpClient en runtime.

Esto es deliberado, no una limitacion temporal: description/canonical/JSON-LD/og:image (SEO) y el <img> real de cada imagen (Google Imagenes) tienen que estar presentes en el HTML servido desde el primer render (SSR/prerender) para que un crawler los indexe -- un fetch asincrono, con o sin timeout() de por medio, corre el riesgo real de que la respuesta no llegue a tiempo para ese render especifico, sirviendo una pagina indexada con esos campos vacios. Se probo la alternativa (JSON en public/config/, editable sin rebuild) y se abandono por esto -- ver @ngx-docs-markdown-kit/parser-md-seo (provideSeoConfig()) para el mismo razonamiento aplicado a nivel de libreria.

Las extensiones opcionales (image, code-block-themes) traen su config de la misma forma, ya como parte de la plantilla (IMAGE_CONFIG/CODE_BLOCK_THEMES_CONFIG existen en el sitio generado sin importar si la extension esta instalada o no -- si no lo esta, simplemente nada los consume, ver los bloques NDMK:OPTIONAL[image]/NDMK:OPTIONAL[code-block-themes]). Instalar una extension mas adelante (npm install @ngx-docs-markdown-kit/parser-md-image sobre un sitio ya generado con --no-image) sigue siendo un paso manual -- restaurar el import + .use() + uso del componente en la plantilla (ver el README de cada extension) -- pero ya no hace falta ningun paso de config aparte, el valor default ya esta en el sitio desde que se genero.

Estado

Implementado: scaffolding base, extensiones opcionales via flags, modo de render elegible (--render-mode=static|server, SSG por default), config del sitio compilada en TS fuente (src/app/core/, config de librerias FrugoCorp organizada bajo frugocorp_modules/<paquete>/config/), estructura de src/app/ por Bounded Contexts + Feature-Driven Development (core/shared globales + bounded-contexts/<contexto>/{core,shared,features}). Ver el README raiz del repositorio para el diseno completo del monorepo.

create-ngx-docs-site

Dependencias:

• @angular/animations: ^22.1.0
• @angular/cdk: ^22.1.0
• @angular/common: ^22.1.0
• @angular/compiler: ^22.1.0
• @angular/core: ^22.1.0
• @angular/forms: ^22.1.0
• @angular/material: ^22.1.0
• @angular/platform-browser: ^22.1.0
• @angular/platform-server: ^22.1.0
• @angular/router: ^22.1.0
• @angular/ssr: ^22.1.3
• @ngx-docs-markdown-kit/parser-md: ^0.1.0
• @ngx-docs-markdown-kit/parser-md-seo: ^0.1.0
• @ngx-docs-markdown-kit/parser-md-code-block: ^0.1.0
• @ngx-docs-markdown-kit/parser-md-code-block-themes: ^0.1.0
• @ngx-docs-markdown-kit/parser-md-image: ^0.1.0
• @ngx-docs-markdown-kit/parser-md-card: ^0.1.0
• @ngx-docs-markdown-kit/parser-md-converter: ^0.1.0
• @ngx-docs-markdown-kit/ui: ^0.1.0
• rxjs: ~7.8.0
• tslib: ^2.3.0

Apartados de create-ngx-docs-site

• Docs -- Documentación de create-ngx-docs-site -- el generador de sitios de documentación en Angular sobre @ngx-docs-markdown-kit.
• Create Ngx Docs Site -- Scaffolding de sitios de documentacion en Angular sobre Markdown, con @ngx-docs-markdown-kit ya conectado.

Docs de create-ngx-docs-site

REGRESAR A APARTADOS DE create-ngx-docs-site

Índice Docs de create-ngx-docs-site

• Primeros pasos -- Requisitos, instalación y estructura de un sitio generado con create-ngx-docs-site.
  • Requisitos -- Qué necesitás instalado antes de crear un sitio con create-ngx-docs-site.
  • Instalación -- Cómo crear un sitio nuevo con "npm create ngx-docs-site" y sus flags opcionales.
  • Estructura del proyecto -- Qué carpetas edita tu equipo y cuáles son infraestructura del generador.
• Escribir contenido -- Cómo agregar páginas y grupos, y qué extensiones de Markdown están disponibles.
  • Páginas y grupos -- Frontmatter con corchetes, el slug explícito, y los 3 archivos reservados con prefijo "___".
  • Extensiones de Markdown -- Bloques de código enriquecidos, tarjetas de comando, imágenes y avisos destacados.
• Configuración -- Nombre, logos, barras visibles y metadatos de SEO del sitio.
  • Nombre y logos -- site.config.ts y resources-config.service.ts -- nombre mostrado y logos claro/oscuro.
  • Barras visibles -- design-config.service.ts -- apagar la barra principal, secundaria o "En esta página".
  • SEO -- seo.config.ts -- descripción, keywords, imágenes Open Graph, dominio y favicons.
• Componentes -- Las 3 barras de navegación, el panel "Tu Proyecto" y el scrollspy.
  • Barras de navegación -- Las 3 barras del sitio -- principal, secundaria y "En esta página".
    • Barra principal -- El rail de iconos por sección, a la izquierda de todo el sitio.
    • Barra secundaria -- El árbol de páginas y grupos de la sección activa.
    • Barra "En esta página" -- Encabezados de la página actual, resaltando el que estás leyendo (scrollspy).
  • Panel "Tu Proyecto" -- Personalizá el nombre de proyecto que aparece en los ejemplos de código del sitio.
  • Scrollspy -- Cómo se decide qué sección está "activa" mientras hacés scroll en una página larga.

Primeros pasos de create-ngx-docs-site

< Índice Docs de create-ngx-docs-site

Requisitos de create-ngx-docs-site

< Primeros pasos de create-ngx-docs-site

create-ngx-docs-site es parte del ecosistema @ngx-docs-markdown-kit, de FrugoCorp.

create-ngx-docs-site genera un proyecto Angular estándar (con SSR) sobre Node -- no hay nada que instalar globalmente antes de correr el generador en sí.

• Node.js 20 o superior (LTS recomendado) -- el sitio generado usa @angular/ssr y type: module, que necesitan una versión reciente.
• npm (viene con Node) -- el generador se invoca con npm create, y el sitio ya generado se instala/corre con npm install/npm start como cualquier proyecto Angular.
• Conocimiento básico de Angular (componentes standalone, signals) si vas a personalizar más allá de editar contenido .md -- editar contenido en sí no requiere tocar Angular para nada.

No hace falta instalar el Angular CLI (@angular/cli) global: el sitio generado ya trae @angular/build como dependencia y expone sus propios scripts de npm (start, build, test).

Instalación de create-ngx-docs-site

< Primeros pasos de create-ngx-docs-site

[!TIP] Los comandos de esta página usan MiProyecto/mi-proyecto como nombre de ejemplo (según haga falta Pascal o kebab-case) -- son los mismos placeholders que reemplaza el panel "Tu Proyecto" (barra 3, ver Panel "Tu Proyecto"). Poné ahí el nombre real de tu proyecto (en snake_case o kebab-case, ej. mi_mejor_proyecto/mi-mejor-proyecto, palabras separadas por _ o -) y los comandos de abajo se actualizan solos, así los copiás y pegás tal cual, sin editar nada a mano.

Un sitio nuevo se crea con:

npm create ngx-docs-site MiProyecto

Esto genera una carpeta (el nombre se convierte a minúsculas-con-guiones para la carpeta/paquete -- MiProyecto termina en mi-proyecto/, aunque MiProyecto tal cual se conserva como nombre mostrado en el sitio). Adentro:

cd mi-proyecto
npm install
npm start

npm start levanta el servidor de desarrollo (ng serve, con recarga en caliente) en http://localhost:4200 -- sin importar el modo de render elegido (ver más abajo), npm start siempre es un dev server normal.

Flags opcionales (--no-<extension>)

Por default el sitio se genera con todas las extensiones del ecosistema instaladas. Cada una se puede omitir con su propio flag:

npm create ngx-docs-site MiProyecto --no-image --no-code-block-themes

| Flag | Qué quita | | --- | --- | | --no-image | @ngx-docs-markdown-kit/parser-md-image -- el fence ```image (ver Extensiones de Markdown) deja de estar disponible. | | --no-code-block-themes | @ngx-docs-markdown-kit/parser-md-code-block-themes -- paletas de color adicionales para el resaltado de código, más allá de las que ya trae parser-md-code-block por default. | | --no-card | @ngx-docs-markdown-kit/parser-md-card -- el fence ```content-card (ver Extensiones de Markdown) deja de estar disponible. |

Un flag desconocido no rompe la generación -- el CLI avisa al final ("no se reconoce ...") por si fue un error de tipeo, pero el sitio se crea igual con el resto de las extensiones.

Modo de render (--render-mode=<static|server>)

Elige, en build-time, cómo se sirve el sitio en producción (npm run build) -- no afecta a npm start/desarrollo, que siempre es un dev server normal sin importar este flag:

npm create ngx-docs-site MiProyecto --render-mode=server

• static (default, no hace falta pasar el flag) -- SSG/prerender puro: npm run build genera solo archivos estáticos (dist/mi-proyecto/browser/, un index.html real por página). En producción no corre ningún proceso Node.js -- se sirve con cualquier hosting estático (nginx, un CDN, GitHub Pages, Netlify, etc.). Recomendado para documentación: todo el contenido sale de Markdown, conocido por completo al compilar.
• server -- SSR completo (@angular/ssr): npm run build genera además dist/mi-proyecto/server/server.mjs, un servidor real que hay que dejar corriendo en producción (node dist/mi-proyecto/server/server.mjs, variable de entorno PORT). Solo tiene sentido si en algún momento el sitio necesita contenido genuinamente dinámico por request -- este template, tal cual viene, no lo tiene en ningún modo (el contenido Markdown se conoce en build-time igual).

Migrar un sitio ya generado de un modo a otro es manual -- editar outputMode/ssr en angular.json y ajustar package.json (agregar/sacar express/@types/express y el script serve:ssr:<nombre>).

Build de producción

npm run build

Genera el bundle de browser + servidor (SSR) bajo dist/<nombre-del-sitio>/, más robots.txt/sitemap.xml reales a partir del contenido (ver SEO) -- ese paso corre ANTES del build de Angular en sí, como parte del mismo script.

Estructura del proyecto de create-ngx-docs-site

< Primeros pasos de create-ngx-docs-site

Un sitio generado separa dos tipos de código por carpeta, para que quede claro a simple vista qué se edita y qué no:

• src/app/ -- tu sitio Angular normal (rutas, componentes propios, core/ con la configuración). Acá es donde tu equipo agrega páginas/lógica propia.
• frugocorp_modules/ -- infraestructura del generador (barras de navegación, servicio de contenido, scripts que leen public/content-parser-md/). No se edita a mano: si necesitás otro comportamiento, se hace desde core/ (ver Barra principal para un ejemplo de por qué nav.ts es el punto de extensión, no estos archivos).

public/content-parser-md/

Todo el contenido real del sitio (lo que ves en esta página, incluida) vive acá como .md -- nunca hardcodeado en un componente. Cada carpeta es un grupo navegable; cada carpeta necesita su propio ___meta.md (título/descripción del grupo). Ver Páginas y grupos para el detalle completo del formato.

El manifiesto generado

npm start/npm run build corren primero un script que escanea public/content-parser-md/ entero y escribe un .ts con la lista completa de páginas (slug, grupo, título, encabezados, orden) -- las 3 barras de navegación, el sitemap y el BreadcrumbList de SEO leen ESE archivo, nunca vuelven a tocar el filesystem. En desarrollo (npm start) ese escaneo corre también en modo watch: guardar un .md regenera el manifiesto y recarga el navegador solo, sin reiniciar nada.

npm-profiles/

Cada sitio trae su propio sistema de perfiles de test, organizado por categoría/sub-grupo/perfil:

npm run profile -- tests unit normal        # suite completa
npm run profile -- tests links internal     # valida links internos del contenido, sin red

Agregar un perfil nuevo es un archivo JSON más bajo npm-profiles/tests/, sin tocar package.json.

Escribir contenido de create-ngx-docs-site

< Índice Docs de create-ngx-docs-site

Páginas y grupos de create-ngx-docs-site

< Escribir contenido de create-ngx-docs-site

Una página

Cualquier .md dentro de public/content-parser-md/ (menos los 3 archivos reservados de más abajo) es una página real. El frontmatter usa corchetes en cada clave:

---
[slug]: mi-pagina
[title]: Mi página
[description]: Descripción para SEO.
[keywords]: palabra1, palabra2
---

# Mi página

Contenido normal en Markdown.

[slug] es obligatorio y siempre explícito -- nunca se deriva del nombre del archivo. Esto es a propósito: el nombre en disco es 100% cosmético (podés usar prefijos de orden propios, mayúsculas, lo que tu equipo prefiera) sin que eso rompa ninguna URL. Un slug inválido o faltante frena la generación con un error que dice exactamente qué archivo lo necesita -- nunca una URL rota en silencio.

El slug solo acepta minúsculas, números y guiones simples entre segmentos (primeros-pasos, no Primeros_Pasos).

Un grupo (carpeta)

Cualquier carpeta con contenido navegable necesita su propio ___meta.md, con el mismo formato de frontmatter ([slug]/[title]/[description]/[keywords], más [icon] si es una sección de nivel superior -- ver Barra principal). Los grupos pueden anidarse tan profundo como haga falta: esta misma página vive 2 niveles adentro de docs/ (docs/content-authoring/pages-and-groups.md).

Orden entre hermanos

Por default, el orden es alfabético por nombre CRUDO de archivo/carpeta. Para forzar un orden distinto, un ___order.md en esa carpeta con una lista de nombres (uno por línea, con o sin viñeta):

- installation.md
- configuration.md

Lo que no aparezca en la lista cae al final, en orden alfabético -- un ___order.md incompleto nunca hace desaparecer contenido.

Los 3 archivos reservados

| Archivo | Para qué | ¿Lo edita tu equipo? | | --- | --- | --- | | ___meta.md | Frontmatter del grupo (título/descripción/slug/icono). | Sí | | ___order.md | Orden explícito de los hijos de esa carpeta. | Sí (opcional) | | ___content_dir.md | Cards con los hijos directos del grupo -- la página que ves al entrar a un grupo sin elegir un hijo todavía. | No -- se regenera solo en cada build/watch. |

El prefijo ___ los agrupa al principio de cualquier listado de carpeta y los distingue de un vistazo del contenido real.

Extensiones de Markdown de create-ngx-docs-site

< Escribir contenido de create-ngx-docs-site

Además del Markdown estándar, el contenido de un sitio generado soporta estas extensiones (cada una viene de un paquete de @ngx-docs-markdown-kit, ya conectado en ContentService).

Bloque de código enriquecido

Un fence simple de 3 backticks se resalta pero sin botón de copiar ni etiqueta de lenguaje. Envolverlo en un fence de 4 backticks ```code-block lo enriquece:

npm install
npm start

Tarjeta de comando

Comando + resultado esperado + una nota, en una sola tarjeta (```card-code-block, 4 backticks):

@description
Corre las pruebas del proyecto.

@command bash
npm test

@result<Resultado esperado> text
Test Files  1 passed (1)
     Tests  3 passed (3)

@note<Nota>
Si falla, revisa que hayas corrido `npm install` primero.

Imagen enriquecida

```image acepta align (left/center/right) y styles (CSS crudo, un escape hatch para radius/sombra/tamaño sin tocar ningún componente):

src: /images/mi-logo.png
alt: Mi logo
description: Texto debajo de la imagen
align: center
styles: height: 200px; border-radius: 12px;

Requiere la extensión image instalada (ver Instalación -- --no-image la omite).

Aviso destacado

Un blockquote que empieza con > [!TIP] (también soporta el resto de las anotaciones estilo GitHub):

> [!TIP]
> Este es un aviso destacado.

Tarjeta de contenido (Material)

```content-card (5 backticks) arma una <mat-card> real de Angular Material a partir de 5 campos, cada uno marcado con @nombre en su propia línea -- todos opcionales, se omiten los que no declares:

@image
src: /images/FrugoCorp-Logo-300x300.jpg
alt: Logo de FrugoCorp
align: center

@title
FrugoCorp

@subtitle
El equipo detrás de `ngx-docs-markdown-kit`

@content
Un **kit de documentación** para Angular, pensado para publicarse como paquetes npm reales.

@actions
[Sitio](https://frugocorp.com)
[Repositorio](https://github.com/frugocorp)

• @image acepta las mismas claves que ```image (arriba).
• @actions son links de Markdown normal ([texto](url)) -- cada uno se renderiza como un botón de Material, en el mismo orden en que los escribas.

Requiere la extensión card instalada (ver Instalación -- --no-card la omite).

Ejemplo en vivo

FrugoCorp

El equipo detrás de ngx-docs-markdown-kit

Un kit de documentación para Angular, pensado para publicarse como paquetes npm reales.

Sitio Repositorio

Cards (autogeneradas)

```cards es la única extensión que no escribís a mano -- la genera el manifiesto en cada ___content_dir.md, con los hijos directos de ese grupo (href|título|descripción por línea). Se documenta acá solo para que sepas de dónde sale la grilla de tarjetas que ves al entrar a cualquier grupo.

Configuración de create-ngx-docs-site

< Índice Docs de create-ngx-docs-site

Nombre y logos de create-ngx-docs-site

< Configuración de create-ngx-docs-site

src/app/core/site.config.ts

Lo único que create-ngx-docs-site sustituye automáticamente al generar el sitio -- el nombre que pasaste a npm create ngx-docs-site <nombre>:

export const SITE_NAME = 'MiProyecto';

src/app/core/resources-config.service.ts

El resto de la identidad visual -- nombre mostrado (si querés que difiera de SITE_NAME) y logos:

export const RESOURCES_CONFIG: ResourcesConfig = {
  siteName: SITE_NAME,
  logoLight: '/images/mi-logo-negro.svg',
  logoDark: '/images/mi-logo-blanco.svg',
};

• logoLight/logoDark -- rutas dentro de public/images/, una por tema (un logo con trazo oscuro se pierde contra un fondo oscuro y viceversa). null en ambos muestra el nombre como texto en la barra principal en vez de una imagen.

Ambos valores viven en TypeScript fuente, no en un JSON de public/ pedido en runtime -- el SSR necesita el valor real desde el primer render (mismo motivo que SEO), así que cualquier cambio requiere recompilar (npm start ya lo hace solo si está corriendo).

Barras visibles de create-ngx-docs-site

< Configuración de create-ngx-docs-site

src/app/core/design-config.service.ts controla qué barras se muestran, de forma global:

export const DESIGN_CONFIG: DesignConfig = {
  showPrimaryBar: true,
  showSecondaryBar: true,
  showOnThisPage: true,
  showProjectNamePanel: true,
};

• showPrimaryBar -- el rail de iconos por sección (ver Barra principal).
• showSecondaryBar -- el árbol de páginas de la sección activa (ver Barra secundaria). Independiente de esto, esta barra ya se oculta sola en una página sin sección (ej. Privacidad) o con menos de 2 items.
• showOnThisPage -- el panel "En esta página" (ver Barra "En esta página"). También se oculta sola en una página con menos de 2 encabezados.
• showProjectNamePanel -- el panel "Tu Proyecto", que vive dentro de "En esta página" pero se apaga aparte -- útil si tu equipo no quiere el mecanismo de reemplazo de placeholders en el contenido.

Apagar una barra acá es global (todo el sitio) -- para ocultarla solo en páginas puntuales, esas páginas ya se resuelven solas por la lógica de "menos de 2 items" de arriba, sin tocar este archivo.

SEO de create-ngx-docs-site

< Configuración de create-ngx-docs-site

frugocorp_modules/parser-md-seo/config/seo.config.ts centraliza los defaults de SEO del sitio -- meta tags, Open Graph/Twitter Card y JSON-LD se arman desde este archivo en cada render (SSR incluido), nunca desde un JSON pedido en runtime, para que un crawler los vea desde el primer HTML servido.

export const SEO_CONFIG: Partial<SeoConfig> = {
  description: 'Sitio de documentación generado con create-ngx-docs-site.',
  keywords: 'documentación, markdown, angular',
  siteUrl: 'https://mi-proyecto.com',
  author: 'MiProyecto',
  contentLanguage: 'es',
  favicons: [
    { rel: 'icon', href: '/images/mi-icono-128x128.png', type: 'image/png', sizes: '128x128' },
  ],
};

Solo hace falta declarar las claves que querés personalizar -- el resto cae al default de la librería.

• siteUrl -- null hasta que configures tu dominio real. Sin esto, canonical/og:url/JSON-LD y el sitemap.xml se omiten (no hay forma de armar URLs absolutas válidas sin un dominio).
• ogImages -- banner panorámico + versión cuadrada (1200x630 y 1080x1080 recomendados), para Open Graph/Twitter Card.
• favicons -- lista de <link rel="icon">/apple-touch-icon/mask-icon. Cada página real del manifiesto (ver Páginas y grupos) aparece automáticamente en sitemap.xml con su lastmod real, sin declarar nada acá.

Cada página puede sobreescribir description/keywords/title en su propio frontmatter (ver Páginas y grupos) -- esos valores ganan sobre el default de este archivo.

Componentes de create-ngx-docs-site

< Índice Docs de create-ngx-docs-site

Barras de navegación de create-ngx-docs-site

< Componentes de create-ngx-docs-site

Barra principal de create-ngx-docs-site

< Barras de navegación de create-ngx-docs-site

Es el rail angosto pegado al borde izquierdo, con un icono por sección de nivel superior -- en este sitio, un solo icono ("Docs"), porque public/content-parser-md/ solo tiene una carpeta de nivel superior con contenido navegable. Si agregaras otra (por ejemplo public/content-parser-md/blog/, con su propio ___meta.md), aparece un segundo icono solo -- nada hardcodeado por nombre de carpeta.

El título y el icono de cada sección salen de [title]/[icon] en el ___meta.md de esa carpeta de nivel superior (ver Páginas y grupos) -- [icon] es un nombre de Material Symbols (ej. description, folder, article).

El item de la sección activa (la que corresponde a la URL actual) se marca con una barra vertical púrpura -- mismo indicador que usan la barra secundaria y la de "En esta página".

También vive acá (no en la barra secundaria) el selector de tema claro/oscuro y el engrane de temas de resaltado de código -- ambos son globales al sitio, no a una sección en particular.

Se apaga por completo con showPrimaryBar: false en Barras visibles.

Barra secundaria de create-ngx-docs-site

< Barras de navegación de create-ngx-docs-site

Muestra el árbol completo de la sección activa -- grupos (como "Primeros pasos" o "Componentes", en este mismo sitio) y páginas sueltas, en el mismo orden que definen sus ___order.md (o alfabético, si no hay ninguno). Un grupo se puede anidar tan profundo como haga falta: esta página misma vive 2 niveles adentro ("Componentes" > "Barras de navegación" > "Barra secundaria").

El encabezado con el nombre de la sección (arriba de todo el árbol) es un link a la página propia de esa sección -- lleva a las Cards con sus grupos/páginas de nivel superior.

Reglas de cuándo se muestra:

• Se oculta sola en cualquier página sin sección activa (por ejemplo Privacidad o Licencia).
• Se oculta sola si le quedarían menos de 2 items de nivel superior (páginas sueltas + grupos) -- un menú de un solo item no aporta nada.
• Se puede colapsar a mano (la flecha de la esquina) -- la preferencia se guarda en este navegador, y un pulso de brillo avisa que sigue ahí cuando cambiás de página mientras está colapsada.
• En móvil se convierte en un drawer que se abre/cierra por completo, en vez de colapsar a una tira angosta.

Se apaga por completo con showSecondaryBar: false en Barras visibles.

Barra "En esta página" de create-ngx-docs-site

< Barras de navegación de create-ngx-docs-site

Lista los encabezados de la página que estás leyendo ahora mismo, indentados según su nivel real (relativo al encabezado MÁS alto que use esa página en particular, para que una página que arranca en ### no quede con sangría desperdiciada). El encabezado que corresponde a donde estás scrolleando se resalta con la misma barra vertical púrpura que usan las otras 2 barras -- ver Scrollspy para cómo se calcula cuál es "el activo".

Al hacer click en un encabezado saltás ahí con scroll suave, sin perder la ruta actual (usa history.replaceState, no una navegación nueva).

Se oculta sola en cualquier página con menos de 2 encabezados -- un panel con un solo link no aporta nada. Igual que la barra secundaria, se puede colapsar a mano (con el mismo aviso de brillo al cambiar de página) y se apaga por completo con showOnThisPage: false en Barras visibles.

Debajo de los encabezados vive el panel Tu Proyecto y, si el sitio tiene más de un lenguaje con resaltado de código, un selector rápido de tema por lenguaje.

Panel "Tu Proyecto" de create-ngx-docs-site

< Componentes de create-ngx-docs-site

Vive en la barra "En esta página", debajo de los encabezados. Deja que cada lector reemplace los placeholders que usan los ejemplos del sitio (npm install MiProyecto, cd mi-proyecto, siteUrl: 'https://mi-proyecto.com') por el nombre real de SU propio proyecto, para poder copiar los comandos tal cual sin editarlos a mano.

El campo pide el nombre en snake_case o kebab-case (ej. mi_mejor_proyecto o mi-mejor-proyecto, palabras separadas por _ o -) -- desde ese único valor, el componente deriva las otras 3 variantes de casing (PascalCase, camelCase, y la que no hayas usado de kebab-case/snake_case) y las guarda todas. También reconoce PascalCase/camelCase de entrada (separa por el límite de mayúscula). Así no importa con qué casing esté escrito un ejemplo puntual en el contenido: los 4 placeholders se reemplazan por igual.

Apagado por default (showProjectNamePanel: false en Barras visibles) -- este sitio lo prende para poder mostrarlo, pero solo tiene sentido si tu propio contenido realmente usa los 4 placeholders de abajo. Si no los usás, dejalo apagado -- prendelo con showProjectNamePanel: true el día que tu equipo empiece a escribir ejemplos con MiProyecto/mi-proyecto/etc.

Cómo funciona:

• El nombre se guarda solo en localStorage, en este navegador -- nunca se manda a ningún servidor.
• El HTML que sirve el servidor (SSR) siempre muestra los placeholders genéricos -- el reemplazo pasa recién en el navegador, apenas Angular arranca, así que un crawler/SEO ve siempre el mismo contenido neutral.
• Se limpia dejando el campo vacío y guardando.

Si estás escribiendo contenido y querés que un ejemplo se beneficie de esto, usá literalmente uno de estos 4 placeholders -- ContentService los reemplaza automáticamente antes de parsear el Markdown:

| Casing | Placeholder | | --- | --- | | Pascal | MiProyecto | | camel | miProyecto | | kebab | mi-proyecto | | snake | mi_proyecto |

Scrollspy de create-ngx-docs-site

< Componentes de create-ngx-docs-site

Mientras scrolleás una página, el sitio necesita saber qué sección estás leyendo AHORA -- eso es lo que resalta en la barra "En esta página" y lo que corrige la URL (#id) sin que vos hagas nada.

La regla: existe una "línea de activación" horizontal, calculada en vivo como la altura real del header más la miga de pan más un margen chico. La sección activa es la última cuyo borde superior ya cruzó esa línea hacia arriba -- no la primera visible, ni la más cercana al centro: mientras el título de una sección siga por encima de la línea, esa sigue siendo "la que estás leyendo", aunque ya casi no se vea en pantalla.

Al entrar a una página con un link a un encabezado puntual (/pagina#seccion), el scrollspy arranca ahí directo (con scroll real) en vez de arrancar siempre desde el principio.

La ÚLTIMA sección de cada página mide, como mínimo, un viewport completo de alto -- sin este detalle, una página corta (con poco contenido después del último título) nunca dejaría que ese título cruce la línea de activación, y el scrollspy se quedaría trabado en la sección anterior.

Create Ngx Docs Site de create-ngx-docs-site

REGRESAR A APARTADOS DE create-ngx-docs-site

GitHub | Sitio | FrugoCorp

create-ngx-docs-site es el punto de entrada del ecosistema: npm create ngx-docs-site genera un sitio de documentacion en Angular listo para usar, con Angular Material + Tailwind CSS de base y todas las librerias de @ngx-docs-markdown-kit ya conectadas -- sin armar la integracion a mano.

Por que un scaffold y no una libreria de componentes suelta

Cada libreria del kit (SEO, bloques de codigo, imagenes, tarjetas, este mismo menu "Explore") es real pero necesita cablearse: rutas, barras de navegacion, manifiesto de contenido, generacion de sitemap/README. El CLI arma esa integracion una vez, con las extensiones opcionales elegibles por flag (--no-image, --no-card, etc.) en vez de que cada equipo la repita a mano.

Que trae de base

Modo de render elegible (--render-mode=static|server, default static -- nginx sirviendo HTML prerenderizado, sin Node en runtime), Docker listo para produccion, y esta misma pagina (home.md) mas el menu "Explore" para que un sitio nuevo pueda contar su propia historia desde el primer npm start.