JASoft.org

El blog de José Manuel Alarcón Aguín. Programación web y mucho más...

MENÚ - JASoft: JM Alarcón

MIIS: Crear sitios avanzados de documentación con Markdown bajo IIS

Aunque esto está listo hace unas semanas, no he tenido tiempo de meterlo aquí hasta ahora.

En los últimos meses he estado trabajando en un proyecto Open Source propio que creo que es bastante interesante. Se trata de un manejador de peticiones para Internet Information Server (IIS) que te permite montar un completo sistema de documentación basado en Markdown y tenerlo listo en unos pocos segundos.

Inicialmente iba a ser algo más sencillo: un simple manejador de peticiones para IIS que transformaría archivos Markdown en HTML para poder servirlos directamente desde un servidor web, ya que no hay nada similar por ahí a pesar de su utilidad y de que hay mucha gente que lo busca. Pero a medida que lo iba construyendo le iba viendo más posibilidades y ha acabado por ser algo mucho más completo. De hecho te permite crear de manera sencilla un gestor de contenidos basado totalmente en Markdown.

Se llama MIIS (Markdown for IIS), y tiene un montón de características:

  • Soporte para las principales extensiones de archivos Markdown: . .md, .markdown, .mdown, .mkdn, .mkd. Las puedes ampliar a tu gusto.
  • Posibilidad de servir HTML5 automáticamente a partir de Markdown, con el estilo estético que prefieras. Se incluyen varios de serie.
  • Soporte de plantillas avanzadas, de modo que puedes crear un sitio completo con navegación y otras características sin tener que hacer nada: escoger una plantilla y listo. He incluido varias de serie, e seguramente incluiré algunas más en el futuro. Son Responsive y funcionan en móviles y otros dispositivos.
  • Alto rendimiento: se hace caché de las plantillas y, opcionalmente, de los propios contenidos Markdown para maximizar el rendimiento en sitios grandes o en servidores con poca capacidad de proceso.
  • Un soporte súper-completo de Markdown y sus principales extensiones (esto no es mérito mío, ya que he usado la mejor biblioteca Open Source para ello en lugar de reinventar la rueda).

MIIS es un híbrido entre un generador de sitios estáticos y un gestor de contenidos tradicional, y en mi opinión elimina las pegas de ambos. Te permite crear, en cero coma, un sitio web de documentación, con navegación, aspecto atractivo y posibilidad de personalizarlo como quieras, y lo único que necesitas para gestionarlo es un editor de texto plano. Es muy fácil de extender con tus propias plantillas o retocando las existentes.

Se instala simplemente copiando unos archivos, por lo que se puede usar incluso en un hosting, subiéndolos por FTP. Funciona en servidores con Windows e IIS, en IISExpress para desarrollo local, y por supuesto en Azure Web Sites. Es posible implementar cualquier tipo de autenticación para controlar el acceso a la documentación (incluso con la autenticación propia de Azure, que es súper-potente y fácil de usar). Y por supuesto puede coexistir con cualquier aplicación que ya tengas, en ASP.NET, ASP.NET MVC 5, PHP, node... cualquier tecnología que soporte IIS. Por supuesto, como Markdown soporte incluir HTML dentro, se puede mezclar HTML especial para ciertas cosas con el texto plano normal de la documentación, dando lugar a híbridos muy chulos.

La propia documentación de MIIS está creada con MIIS :-) En Krasis y campusMVP ya lo estamos empleando, por ejemplo, en la nueva Intranet de plantillas y documentación interna con acceso restringido a empleados, e iremos ampliando su uso para otras aplicaciones en breve.

La única "pega": he creado todo el software y su documentación en inglés. No hay versión en español. Si alguien quiere ayudarme me vendría bien alguien que hiciera:

  • Traducción de la documentación (el sitio web fundamentalmente) al español y otros idiomas.
  • Creación de más plantillas de sitio.

Para ello es muy sencillo: sigue el flujo normal de colaboración de GitHub.

Puedes ponerlo en marcha en menos de 30 segundos si ya tienes documentación en Markdown. Para ello lee la documentación oficial del proyecto, y descarga la última release desde el enlace que encontrarás en ésta. En la documentación se explica con detalle cómo ponerlo en marcha, personalizarlo, crear tus propias plantillas, ponerlo a andar en IIS y en Azure, etc...

Si lo utilizas para algún proyecto público mándame unas líneas a través de Twitter o creando un "Issue" en Github con la etiqueta "Showcase".

Y si me ayudas con las cosas que pongo más arriba, te lo agradeceré mucho ;-)

¡Espero que te sea útil!

José Manuel Alarcón José Manuel Alarcón
Fundador y director de campusMVP.es, el proyecto de referencia en formación on-line para programadores en lengua española. Autor de varios libros y cientos de artículos. Galardonado como MVP de Microsoft desde 2004. Gallego de Vigo, amante de la ciencia y la tecnología, la música y la lectura. Ayudando a la gente en Internet desde 1996.
Descarga GRATIS mi último libro (no técnico): "Tres Monos, Diez Minutos".
Banner

Agregar comentario