Cómo crear una base de conocimientos de soporte compatible con SEO: la guía completa para una solución de documentación escalable

Publicado: 2016-10-26

Una vez que crece la base de usuarios de su startup, el soporte se convierte en una parte fundamental de su negocio. Configurar una solución sólida de base de conocimientos es una inversión importante a largo plazo que, con suerte, si se hace correctamente, valdrá la pena al reducir la carga de soporte, ampliar el alcance de SEO de su sitio y generar nuevos clientes potenciales que de otro modo no se habrían obtenido.

Esta es una guía completa y técnica paso a paso para desarrolladores. Si no es un desarrollador, probablemente debería enviar este artículo a su CTO. Él/ella te lo agradecerá.

TL;DR: Finalmente construimos y lanzamos nuestra base de conocimiento semiestática basada en rebajas para nuestra plataforma de monetización Freemius, usando WordPress. Estoy compartiendo el libro de cocina completo de nuestra investigación aquí; por qué elegimos WordPress en lugar de soluciones SaaS y generadores estáticos; cómo lo hicimos (incluidas todas las personalizaciones de código y la configuración a nivel de servidor), lo que aprendimos y cómo puede replicar ese proceso para ahorrar un tiempo valioso y configurar su propio rápido, escalable, sostenible, seguro y semi- KB estática (Base de conocimiento) para su propio complemento, tema o cualquier otro producto digital.

Esta guía de 15 minutos le ahorrará 44 horas (usamos seguimiento de tiempo) de investigación, personalización, pruebas y optimización. Si aún no está en la etapa de configurar su propio centro de documentación, simplemente marque esta página y regrese cuando sea el momento adecuado.

¿Estás listo? Aquí vamos.

Motivación
¿Qué debe buscar en una solución de documentación?
1. Escalable y duradero
2. Oficina virtual fácil de usar
3. Sostenible
4. SEO optimizado
5. Compatible con la marca
¡Es difícil elegir la plataforma de documentación adecuada!
- Base de conocimiento Software como servicio
- Bases de conocimiento estáticas
- Bases de conocimiento impulsadas por WordPress
Por qué no elegimos Help Scout Docs o cualquier otra base de conocimientos de SaaSy
Por qué elegimos WordPress en lugar de generadores de sitios estáticos para nuestra base de conocimientos
¿Por qué elegimos el complemento de WordPress weDocs para nuestra base de conocimientos?
Instalación y personalización de la solución de documentación weDocs
- Adición de metadatos de fragmentos enriquecidos de migas de pan
- Personalización de la estructura de URL de la base de conocimientos (enlaces permanentes)
- Agregar una página de inicio bonita a la base de conocimientos de weDocs
- Cómo hacer que weDocs sea amigable para dispositivos móviles/responsivo
Uso de Markdown en lugar de edición enriquecida de HTML
- Elegir e instalar un complemento de WordPress Markdown
- Agregar compatibilidad con YouTube y Vimeo Markdown
- Añadir Nice Callouts Shortcodes Soporte
- Agregando SyntaxHighlighter para Pretty Code
¿Cómo hicimos que nuestra base de conocimientos de WordPress fuera súper rápida?
- Adición de permisos de disco
- Habilitación del almacenamiento en caché
- Configuración del almacenamiento en caché a nivel de servidor
- Agregar CDN
¿Cómo personalizamos la búsqueda de KB para servir datos almacenados en caché?
¿Cómo aseguramos nuestra base de conocimientos de WordPress?
Ahora tu

Motivación

La documentación siempre estuvo en nuestra lista de TODO desde los primeros días de Freemius. Habiendo dicho eso, cuando el producto está en las primeras etapas, no tiene sentido apresurarse y documentarlo. El enfoque debe centrarse en validar suposiciones e iteraciones rápidas, hasta llegar a un ajuste satisfactorio del producto al mercado. Comenzamos Freemius hace aproximadamente un año y medio, y finalmente sentimos que era hora de priorizar la documentación.

¿Qué debe buscar en una solución de documentación?

Antes de apresurarme a encontrar una solución, quería tener algún tipo de plan. Por lo tanto, elaboré la siguiente lista de requisitos:

Escalable y duradero

Como cualquier otra solución basada en web, tiene que poder escalar con nuestro tráfico manteniendo el mismo rendimiento. También DEBE continuar sin esfuerzo encontrar respuestas cuando la base de conocimiento crece más allá de una docena de artículos. En otras palabras, ¡buena búsqueda!

Oficina virtual fácil de usar

Agregar y editar artículos de documentación debería ser fácil para cualquier miembro del equipo, ya sean desarrolladores o no.

Sostenible

Nada dura para siempre. Las tendencias de diseño están cambiando y la tecnología está evolucionando todo el tiempo. Por lo tanto, debería ser relativamente fácil modificar la interfaz de usuario de la base de conocimiento y, en casos extremos, exportar fácilmente los datos y migrar a un sistema completamente diferente.

SEO optimizado

La documentación es contenido. A diferencia de las publicaciones de su blog, la documentación de la base de conocimientos se centra únicamente en su producto. Tus palabras clave. Es una excelente manera de potenciar su autoridad de SEO en lo que sea que venda.

Además, cuando los usuarios buscan algo, el hábito común es usar un motor de búsqueda de inmediato. Es más fácil que abrir su sitio, buscar el vínculo Base de conocimientos/Centro de ayuda/Documentos y luego buscar una solución. Por lo tanto, es mejor que se asegure de que el contenido de su documentación sea visible para los motores de búsqueda y esté optimizado para ellos, especialmente para Google si se dirige al mercado de habla inglesa.

Compatible con la marca

La apariencia de la Base de conocimientos debe coincidir con el lenguaje de diseño y la marca de nuestra empresa. Esto incluye colores, fuentes, estilo de encabezado y pie de página, etc.

¡Es difícil elegir la plataforma de documentación adecuada!

Siguiendo mi flujo de descubrimiento natural, fui a pedirle consejo a Google. Esta vez, Google no fue útil. Los resultados de la búsqueda fueron abrumadores. No solo hay tantas opciones en el mercado, sino que las soluciones son intrínsecamente diferentes.

Google no fue útil. Hay tantas opciones en el mercado y las soluciones son inherentemente diferentes.Tweet

Base de conocimiento Software como servicio

Existen soluciones de software de base de conocimientos designadas impulsadas por empresas de soporte técnico como Help Scout Docs y Zendesk Help Center.

Bases de conocimiento estáticas

Los generadores de sitios estáticos son cada vez más populares. Si no está familiarizado con el concepto, la idea general es que la mayoría de los sitios web son bastante estáticos (incluido su blog de WordPress) y no hay una razón real para ejecutar una pila de back-end agotadora como WordPress / PHP / MySql. En su lugar, trasladar el trabajo pesado a un motor previo a la implementación que generará páginas HTML estáticas que se pueden alojar en CDN sin siquiera tocar sus servidores. Es rentable, escalable y seguro.

Hay cientos de generadores por ahí, y motores como Jekyll y Hugo son muy adoptados entre la comunidad de desarrolladores incondicionales (¡por una buena razón!).

Bases de conocimiento impulsadas por WordPress

Encontré más de 20 complementos gratuitos de la base de conocimientos en el repositorio de WordPress.org, otra docena de complementos de documentación pagados en CodeCanyon y Google, y otra docena de temas del Centro de ayuda.

¿Sentirse confundido? Definitivamente hice ¯\(°_o)/¯

Como puede ver, demasiadas opciones. Decidí probar otra estrategia: pedir una recomendación de personas en cuya opinión confío. Soy miembro de un grupo de Facebook llamado Venta de productos de WordPress del que forman parte muchos de mis amigos y personas líderes en productos de WordPress. Estoy bastante seguro de que el 90% de ellos se han enfrentado al mismo desafío antes que yo, por lo que definitivamente valió la pena intentarlo.

Antes de subir mi pregunta, hice una búsqueda y encontré un hilo de 2015, iniciado por Jean Galea de WP Mayor, que hace exactamente la misma pregunta:

¡Increíble! Pensé dentro de mí. Y luego comencé a leer las respuestas...

Adrian Labos está usando Zendesk Help Desk
Pippin Williamson (Pippin Plugins) y Adam Pickering (Astoundify) están usando Help Scout Docs
Phil Derksen está usando WordPress con el tema KnowHow
Dejan Markovic (Hype Social) está usando WordPress con el complemento weDocs
Devin Walker (WordImpress) usa WordPress con CPT y el complemento ACF.
Ahmad Awais, que creó el tema DocPress, dice que "mantener un sitio de documentos con WordPress se ha vuelto ineficiente cuando crece la cantidad de productos" y ahora está creando una base de conocimientos estática con el motor de plantillas Jade.
Tom Hemsley (complemento Mega Menu) recomendó usar WordPress con el complemento Heroic Knowledge Base.
Hubo otras tres respuestas sobre complementos adicionales de WordPress por parte de sus autores que forman parte del grupo.

Como puede ver, simplemente no hay consenso. Desafortunadamente, esto no fue muy útil.

Maldita sea, es hora de investigar un poco...

CONSEJO: Como nota al margen, si usted es una persona de productos en la esfera de WordPress, le recomiendo que se postule para este grupo.

Suscríbase y obtenga una copia gratuita de nuestro

Complemento de WordPress Libro de negocios

Exactamente cómo crear un próspero negocio de complementos de WordPress en la economía de suscripción.

¡Gracias por suscribirte!

- Acabamos de enviar su copia de 'El libro de negocios del complemento de WordPress' a .

¿Tienes un error tipográfico en tu correo electrónico? haga clic aquí para editar la dirección de correo electrónico y enviar de nuevo.

Por qué no elegimos Help Scout Docs o cualquier otra base de conocimientos de SaaSy

Soy fanático de Help Scout y los usamos para nuestro sistema de tickets de soporte. De hecho, soy amigo de los fundadores. En 2011, estuvimos trabajando escritorio 2 y pasando el rato juntos durante 4 meses, mientras participábamos en el programa acelerador Techstars en Boston. Eso fue cuando Help Scout era solo Denny, Jared y Nick.

Docs es una solución de documentación bastante sólida y probablemente la forma más fácil y rápida de hacerlo. También es sorprendentemente personalizable. Pero al igual que las otras plataformas SaaS, viene con fallas de SEO.

1. La configuración de una Base de conocimiento, o cualquier otro contenido, en un subdirectorio sigue siendo significativamente mejor que en un subdominio en términos de clasificación de búsqueda. Rand Fishkin, el fundador de MOZ (la empresa de SEO líder en el mundo) tiene un excelente video de 2015 con casos de uso reales que tratan ese tema.

Desafortunadamente, debido a la forma en que funcionan los archivos de la zona DNS, no hay forma de configurar un CNAME en un subdirectorio.

Para asegurarme de no perderme ninguna solución, me comuniqué con el equipo de soporte de Help Scout y esta es la respuesta que recibí:

“Odio venir con malas noticias, pero no hay manera de tener Docs en un subdirectorio. Tenemos una API para Docs que le permite exportar su sitio y alojarlo usted mismo, pero tendría que reconstruir parte del aspecto y la funcionalidad: http://developer.helpscout.net/docs-api/
Me temo que esta sería la única solución si aún desea usar Docs y tenerlo como un subdirectorio.

2. No revisé las otras soluciones debido a la razón anterior, pero Help Scout Docs en particular, no incluye metadatos Rich-Snippets para migas de pan y búsqueda.

Así es como se ve un resultado de Help Scout Docs en la SERP (página de resultados del motor de búsqueda) de Google:

Este es el resultado de una página que tiene metadatos de fragmentos enriquecidos de migas de pan:

Y este es el resultado de una página que tiene metadatos de búsqueda de fragmentos enriquecidos:

No profundizaré en ese tema, pero en general, los metadatos de fragmentos enriquecidos ayudan al motor de búsqueda a comprender mejor el contenido de su sitio y su estructura. Los principales motores de búsqueda del mundo: Google, Yahoo y Bing; puede traducir estos datos en imágenes que aumentan el CTR de búsqueda (tasa de clics). En pocas palabras, obtendrá más tráfico.

También hice ping a Chris Mooney, cofundador de HeroThemes, una empresa que se centra exclusivamente en soluciones de base de conocimientos, y confirmó que el SEO es una de las principales razones por las que los clientes migran a su solución de documentación local.

Solo para enfatizar la importancia del valor de SEO que puede obtener de una documentación bien escrita, me gustaría compartir una breve historia. En 2011 me reuní con Elad Eran, vicepresidente de soluciones para clientes de WiX. Eran explicó con orgullo que su software de base de conocimientos y los foros de soporte son uno de los principales catalizadores que ayudaron a WiX a posicionarse alto en Google y obtener tráfico orgánico, gratuito y de alta calidad.

El software de la base de conocimientos y los foros de soporte son uno de los principales catalizadores que ayudaron a WiX a posicionarse alto en Google y obtener tráfico orgánico, gratuito y de alta calidad.Tweet

Si es bueno para WiX, debería ser bueno para nosotros

Por qué elegimos WordPress en lugar de generadores de sitios estáticos para nuestra base de conocimientos

Los principales beneficios de volverse estático con un motor como Jekyll son la velocidad, la escalabilidad y la seguridad.

¿Podemos conseguirlos con WordPress? La respuesta es: casi.

Dado que las páginas de documentación son estáticas (excepto para la búsqueda), podemos instalar fácilmente uno de las docenas de complementos gratuitos de almacenamiento en caché de WordPress, configurar Nginx para servir los archivos almacenados en caché directamente desde el disco sin usar el motor de WordPress, y también usar un servicio gratuito de CDN como CloudFlare para distribuir nuestros archivos en diferentes centros de datos alrededor del mundo. Puede sonar complejo, pero en realidad no lo es, y lo explicaré todo pronto.

Eso hará que nuestra interfaz de documentación sea absolutamente estática. Escalará muy bien y será súper rápido (porque es estático). W00t! W00t!

En términos de seguridad, bueno, nada es perfecto. Pero podemos tomar algunas precauciones básicas utilizando algunos complementos gratuitos y alguna configuración a nivel de servidor, que reducirá la posibilidad de un ataque en un 99,9 %. Hablaré explícitamente de eso en un momento, incluidos todos los ingredientes.

Por otro lado, las desventajas del enfoque estático para nuestro equipo fueron:

Como equipo, tendremos que adquirir un nuevo conjunto de habilidades técnicas, configurar un entorno de desarrollo adicional y tener un proceso de implementación continuo para asegurarnos de que agregar o editar archivos no requiera la intervención de un desarrollador. Definitivamente es factible, pero lleva tiempo.
La búsqueda es (principalmente) una funcionalidad dinámica, por lo que si nos volvemos estáticos, tendremos que implementar alguna API RESTful o integrar un servicio de búsqueda de terceros como Algolia. Otro dolor de cabeza con el que lidiar.
El control de versiones no es un CMS. Por mucho que me encanten GitHub y BitBucket, pueden asustar a las personas que no son expertas en tecnología. Aunque todos los miembros de nuestro equipo son desarrolladores en su experiencia, es probable que esto cambie en el futuro.

SUGERENCIA: Vale la pena mencionar que durante mi investigación encontré un ingenioso proyecto llamado Prose.io que proporciona una edición de contenido WYSIWYG simple de archivos de GitHub y BitBucket.

En resumen, podemos obtener la mayoría de los beneficios de los sitios estáticos sin perder la flexibilidad de WordPress, manteniendo el editor de CMS fácil de usar y obteniendo la edición en tiempo real sin un proceso de implementación continuo.

¿Por qué elegimos el complemento de WordPress weDocs para nuestra base de conocimientos?

Como mencioné antes, había visto al menos 30 complementos y temas de WordPress para Bases de conocimiento.

Dado que estamos ejecutando una startup, no es factible evaluarlos todos. Así que tratemos de ir con la eliminación.

¡Ya están disponibles los temas de la base de conocimientos!

Elegimos no ir con ningún tema de documentación porque la mayoría de ellos usan el objeto de post predeterminado y la taxonomía de category para los artículos de documentación. Esta solución puede funcionar si configura una instancia de WordPress dedicada solo para su aplicación de base de conocimientos. Si desea tener todo su sitio en la misma instalación de WordPress, incluido su blog, las cosas pueden complicarse y probablemente se complicarán debido a la combinación de tipos de contenido.

Yay, ahora solo tenemos otros 20 complementos para probar...

Probé cuatro complementos gratuitos diferentes:

Base de conocimiento CPT
Base de conocimientos de WP
Ayuda de WP
weDocs

Bastante rápido descubrí que todos aprovechan el CPT de WordPress (Tipos de publicaciones personalizadas) y la taxonomía personalizada para etiquetas y categorías. La principal y única diferencia significativa está en la jerarquía de la estructura de datos.

Knowledge Base CPT y WP Knowledge Base son planos. Al igual que con las publicaciones de blog, hay categorías, etiquetas y artículos. No hay forma de asociar un artículo con un artículo principal.

Entonces, la estructura de una base de conocimiento con esos complementos será categorías como secciones y publicaciones como documentos.

 Categoría 1
↳ Documento 1
↳ Documento 2

Categoría 2
↳ Documento 3
↳ Documento 4

El beneficio de esa estructura es que puede asociar un documento con varias categorías y hacer que aparezca en varias secciones.

 Categoría 1
↳ Documento 1
...
Categoría 2
↳ Documento 3
↳ Documento 1

Por otro lado, la estructura de artículos de WP Help y weDocs es similar a las páginas. Cada documento se puede asociar con cualquier otro documento como padre. Pero, solo se puede asociar con un padre (no como con una categoría).

 Documento 1
↳ Documento 2
↳ Documento 3
↳ Documento 4
↳ Documento 5
↳ Documento 6

Hay dos beneficios para esa estructura:

Es más estructurado. Te obliga a pensar cuál es exactamente el lugar más adecuado para añadir el artículo de documentación.
Las categorías no tienen un "orden" específico. Por lo tanto, no existe una forma inmediata de organizar las categorías de la forma en que es posible con las publicaciones que tienen una propiedad menu_order .

Las razones anteriores fueron exactamente por qué decidimos optar por los complementos jerárquicos.

Genial, ahora sé el tipo de estructura de datos que necesitamos para nuestra documentación.

Luego pasé un tiempo leyendo sobre dos complementos premium: wpDocs (la versión pro de WP Knowledge Base) y Heroic Knowledge Base. Ambos se ven visualmente impresionantes, pero...

No pude encontrar ninguna diferencia significativa entre esos dos complementos premium y los complementos gratuitos.
Ambos complementos utilizan la estructura de datos plana, que decidimos no utilizar.

Entonces, sí, probablemente hubo otros 10 complementos que ni siquiera miré, pero el patrón era claro.

Decidimos usar weDocs en lugar de WP Help por varias razones:

La interfaz de usuario de arrastrar y soltar de la configuración del administrador de weDocs es moderna, fácil de usar y visualmente atractiva.
WP Help no viene con una taxonomía personalizada para los documentos. Lo que significa que las categorías y las etiquetas no se entregan listas para usar.
WP Help no admite migas de pan en absoluto.
weDocs se envió con un conjunto de plantillas personalizadas que harán que la documentación se vea bien de inmediato (obviamente, se requiere alguna personalización de la interfaz de usuario).
weDocs tiene un flujo de interfaz de usuario continuo. Al final de cada artículo, puede navegar al siguiente en línea.

Pasemos a la parte divertida: la implementación...

Instalación y personalización de la solución de documentación weDocs

Para comenzar, descargue e instale weDocs directamente desde el repositorio de WordPress.org:
https://wordpress.org/plugins/wedocs/

Ahora es el momento de hacer algunas personalizaciones:

Adición de metadatos de fragmentos enriquecidos de migas de pan

Como no queríamos cambiar el complemento real (si es posible), usamos la plantilla de weDocs y las funciones del tema.php para anular la representación predeterminada de las migas de pan.

Copie /wedocs/templates/single-docs.php en /your-theme/wedocs/single-docs.php .
Agrega el siguiente código al archivo functions.php del tema:
Abra /your-theme/wedocs/single-docs.php y reemplace la llamada a wedocs_breadcrumbs() con freemius_wedocs_breadcrumbs() .
Dado que también modificamos la estructura HTML de las migas de pan a una lista desordenada ( <ul> ) para una mejor semántica, agregue el siguiente código SASS a su tema:

Para completar los fragmentos enriquecidos, deberá agregar el siguiente código a su etiqueta <body> :

<body<?php if ('docs' === get_post_type()){     echo ' itemscope itemtype="http://schema.org/WebPage"'; } ?>>

Personalización de la estructura de URL de la base de conocimientos (enlaces permanentes)

weDocs se envía con la siguiente estructura de enlaces permanentes predeterminada:
your-site.com/wordpress-root/docs/

Queríamos tener nuestra documentación en freemius.com/help/documentation/ que debería tener una mejor clasificación en SEO al buscar documentación. También queríamos mantener la página de "ayuda" para agregar un Centro de ayuda en el futuro, de modo que podamos usar estructuras de URL como /help/faq/ para una página de preguntas frecuentes y /help/forum/ para un foro.

Podríamos lograrlo fácilmente modificando las reglas de reescritura de los docs CPT en el código del complemento. Pero como queremos evitar cambiar el código del complemento, encontramos una manera de hacerlo indirectamente en el archivo functions.php del tema:
Además, hemos agregado soporte para extractos de artículos (los necesitamos para la próxima personalización), autor de documentos, campos personalizados y atributos de página. Importante: weDocs está estructurado de forma predeterminada para la base de conocimientos de varios productos. Por lo tanto, si desea tener la estructura de /help/documentation/ , asegúrese de que el documento de nivel superior que cree en la oficina administrativa se llame Documentación (el slug debe ser documentation ).

Agregar una página de inicio bonita a la base de conocimientos de weDocs

De manera predeterminada, weDocs se envía con un código abreviado que puede ayudarlo a crear una página de inicio que se verá así:

No está mal, pero personalmente prefiero el diseño generado por Help Scout Docs :

Proporciona una breve descripción de cada sección y me parece más atractivo visualmente. Primero, creemos las plantillas de PHP agregando docs-header-main.php y docs-sections.php en la carpeta /your-theme/wedocs/ . Puede encontrar el código en la siguiente esencia: https://gist.github.com/vovafeldman/adbf1c071a08b7565df11d709b2f1240 Si se sumerge en el código del archivo docs-header-main.php , notará que también me colé en la búsqueda rica fragmentos de metadatos. Ahora, dado que el artículo /help/documentation/ es solo otro artículo en la Base de conocimiento, la plantilla predeterminada que utilizará WordPress es /wedocs/single-docs.php . Por lo tanto, debemos agregar el siguiente fragmento de código en la parte superior de ese archivo, para cargar las nuevas plantillas de secciones cuando el padre del artículo no está configurado:

if ( empty( $post->post_parent ) ) {
  wedocs_get_template_part( 'docs', 'header-main' );
  wedocs_get_template_part( 'docs', 'sections' );

  return;
}

Cómo hacer que weDocs sea amigable para dispositivos móviles/responsivo

Desafortunadamente, weDocs no se entrega con reglas CSS receptivas. Así es como se ve en la base de conocimientos de weDevs (los desarrolladores de weDocs):

No voy a sumergirme en el CSS, pero en general, agregamos consultas de medios que:

Esconde el pan rallado.
Haga que el contenido sea de ancho completo con un buen relleno.
Se movió la barra lateral de navegación y la búsqueda a la parte inferior, justo antes del pie de página.

Aquí está el resultado:

Y así es como se ve la página de secciones:

¡Genial! Hemos terminado con la personalización de weDocs.

Uso de Markdown en lugar de edición enriquecida de HTML

Uno de los requisitos iniciales de la KB era la sostenibilidad: la capacidad de cambiar fácilmente el diseño y potencialmente una plataforma (¿recuerdas?). El uso de la edición de contenido enriquecido HTML es un arma de doble filo. Por un lado, es extremadamente flexible y te da la libertad de personalizar el estilo del contenido como desees. Por otro lado, esta falta de estructura permite que cada escritor de contenido haga lo que quiera. Esto no es sostenible, hace que los cambios de diseño sean complejos y que la migración sea aún más difícil. Por ejemplo, usar <strong> frente <b> . O usando tablas basadas en <table> vs. <div> . Esas son decisiones relacionadas con la sintaxis, y cada persona tiene su estilo de escritura único.

En lo que los redactores de contenido deberían centrarse realmente es en el contenido y la semántica, no en el diseño.

Hay muchos lenguajes de marcado con sintaxis de formato de texto sin formato, aunque Markdown fue la elección natural, ya que es ampliamente utilizado por gigantes como GitHub, Atlassian y WordPress.

Elegir e instalar un complemento de WordPress Markdown

Solo hay dos complementos de Markdown en el repositorio de WordPress.org que tienen más de 1,000 instalaciones activas. WP-Markdown y JP Markdown. Sí, Jetpack también tiene un módulo Markdown, pero no tenía sentido instalar este "monstruo" solo para un módulo. Inicialmente, instalé WP-Markdown porque, según las capturas de pantalla, tenía la opción de seleccionar fácilmente qué tipos de publicaciones admitirían Markdown. Desafortunadamente, el complemento no funcionó (la última actualización fue hace más de 3 años), por lo que terminamos sin usarlo. Luego, instalé JP Markdown. El complemento funcionó pero tenía algunas cosas que no me gustaban:

La rebaja se activó automáticamente en todas las publicaciones y páginas.
La sintaxis de rebajas no se conservó, se convirtió automáticamente a HTML con estilo:

Esto es malo porque los datos se almacenan en la base de datos como HTML enriquecido y no como descuento (verifiqué eso). Además, no agrega ninguna restricción en la edición de HTML enriquecido. Entonces, si en el futuro nos gustaría migrar a otro sistema, no hay forma de exportar el descuento.

Luego encontré WP Markdown Editor que usa el módulo Markdown de Jetpack, y ese fue el que terminamos usando. Aunque todavía tuvimos que hacer algunas personalizaciones:

El complemento deshabilita la edición enriquecida de todas las publicaciones y páginas al activarse. Queríamos deshacernos de la edición enriquecida solo en nuestras páginas de documentación.
El complemento anula el editor existente con su propio editor de rebajas para todas las publicaciones y páginas. Nuevamente, queríamos tener eso solo en nuestras páginas de documentación.

Puedes ver esos cambios aquí:
https://github.com/Freemius/wp-markdown-editor/commit/706bce0c23943c82d102c67a09e18dac32c66207

Puede descargar la versión bifurcada desde aquí (solo unos pequeños cambios):
https://github.com/Freemius/wp-markdown-editor

Luego, agregamos una función corta que registra docs CPT para admitir la edición de rebajas y cancela el registro post y tipos de page para mantener el editor HTML enriquecido:

Finalmente, tuvimos que modificar la funcionalidad de exportación predeterminada de WordPress para que exporte el código de descuento y no el contenido rico en HTML. Lo hicimos enganchándonos al filtro the_content_export :
Impresionante: nuestra KB funciona con Markdown y se puede exportar fácilmente.

Agregar compatibilidad con YouTube y Vimeo Markdown

Los videos son una parte esencial de cualquier base de conocimientos. Desafortunadamente, Markdown no admite videos. Afortunadamente, WordPress hace que sea muy fácil agregar códigos abreviados y con unas pocas líneas de código. Enriquecimos nuestra sintaxis Markdown para admitir la adición de videos de YouTube y Vimeo:

Como beneficio adicional, hicimos que el tamaño del video sea receptivo y compatible con dispositivos móviles, y la adición de videos ahora es intuitiva y directa con la identificación del video:
[youtube gj6aoYG4fUI]
[vimeo 185625717]

Añadir Nice Callouts Shortcodes Soporte

La sintaxis predeterminada de Markdown admite comillas en bloque, pero no viene con semántica para diferentes llamadas, como sugerencias y advertencias, que no son obligatorias, pero son importantes para una buena base de conocimientos.

Códigos cortos de WordPress al rescate de nuevo

Y así es como se ve en la interfaz:

Hemos agregado el prefijo fs_ para evitar posibles conflictos con complementos que podamos instalar en el futuro.

Agregando SyntaxHighlighter para Pretty Code

Ni WordPress ni WP Markdown Editor vienen con resaltado de sintaxis de código. Dado que Freemius es una plataforma para desarrolladores y nuestra documentación viene con ejemplos de código, la adición del resaltado de sintaxis fue crucial. Elegimos usar SyntaxHighlighter Evolved ya que funciona con Automattic, al igual que el módulo Markdown principal de Jetpack que usa el complemento WP Markdown Editor. Mirar el código de representación de Markdown revela que en realidad se integraron juntos:

$this->use_code_shortcode = class_exists( 'SyntaxHighlighter' );

¡Increíble! ¿Derecha? Desafortunadamente, parece que nada es perfecto listo para usar y el código se representó incorrectamente. Estaba estropeando las secciones de código de varias líneas de Markdown al escapar caracteres especiales a sus entidades HTML correspondientes. No solo estaba "rompiendo" el código renderizado en la interfaz, sino que estaba almacenando una versión HTML escapada de las partes del código de Markdown en la base de datos. Y eso es malo para la preservación del contenido y la posible exportación de datos. Por lo tanto, no tuvimos más remedio que hacer algunos ajustes en el código del complemento. Puedes ver los cambios exactos aquí:
https://github.com/Freemius/wp-markdown-editor/commit/672695be8b29c57f7fa7ca580d29368b9e57af68

Ahora tenemos una hermosa base de conocimientos basada en Markdown, compatible con dispositivos móviles, con soporte de video, llamadas y resaltado de sintaxis de código. ¡Sí!

Todavía tenemos que hacerlo rápido y seguro (¡casi llegamos!).

¿Cómo hicimos que nuestra base de conocimientos de WordPress fuera súper rápida?

Elegimos WP Super Cache porque es muy popular (más de 1 millón de instalaciones activas), desarrollado y mantenido por Automattic, gratuito y relativamente fácil de configurar.

Adición de permisos de disco

Cree una carpeta de almacenamiento en caché de escritura: mkdir /path/to/your/wordpress/wp-content/cache/ setfacl -Rm user:apache:rwx /path/to/your/wordpress/wp-content/cache Si la línea de permisos no lo hizo trabajo, use lo siguiente: chmod 777 /path/to/your/wordpress/wp-content/cache/

Habilitación del almacenamiento en caché

Habilite el almacenamiento en caché agregando lo siguiente a su archivo wp-config.php :

/** Enable Caching */
define('WP_CACHE', true);
define( 'WPCACHEHOME', '/path/to/your/wordpress/wp-content/plugins/wp-super-cache/' );

Ahora todo lo que necesitamos es activar el almacenamiento en caché, puede hacerlo a través de WP Admin → Configuración → WP Super Cache: No olvide hacer clic en el botón "Actualizar estado" para guardar. Puede verificar que el almacenamiento en caché funciona abriendo cualquier página de su sitio de WordPress en modo de incógnito y verificando el código fuente. Cuando WP Super Cache está funcionando, debería ver el siguiente comentario HTML en la parte inferior del código fuente de la página:

<!-- Dynamic page generated in 0.848 seconds. -->
<!-- Cached page generated by WP-Super-Cache on 2016-10-13 21:35:40 -->

<!-- super cache -->

Eso ya es mucho mejor que servir las páginas sin almacenamiento en caché. Pero, esto aún desencadena toda la pila de PHP, WordPress y MySql. Si queremos que nuestro sitio sea ultrarrápido, debemos agregar almacenamiento en caché a nivel de servidor.

Configuración del almacenamiento en caché a nivel de servidor

Si usa Nginx, como nosotros, esta es la configuración que hemos usado: Reglas de configuración de WP Super Cache Nginx CONSEJO: Las reglas de configuración de Nginx incluyen un montón de reglas if . Para ahorrarle un tiempo valioso, asegúrese de que todas las reglas if fuera de la directiva de location ; de lo contrario, se interrumpirá todo el procesamiento (perdí algunas horas resolviendo esto). Si usa Apache, puede encontrar las reglas de .htaccess mod_rewrite directamente en la página de instrucciones de instalación del complemento en WordPress.org: https://wordpress.org/plugins/wp-super-cache/installation/ La forma más fácil de probar el El almacenamiento en caché a nivel de servidor sin afectar su sitio es siguiendo estos pasos:

Cree y publique una publicación ficticia, configure el siguiente slug `dummy-cache-test`.
Cargue la página en el modo de navegador de incógnito, asegurándose de que esté en caché.

Agregue el siguiente código a la parte superior de su archivo wp-config.php :

if ( false !== strpos($_SERVER[REQUEST_URI], 'dummy-cache-test') {
    echo 'Server caching is off';
    exit;
}

Después de agregar el código, vuelva a cargar la página en el mismo modo de navegador de incógnito. Si la página se carga correctamente, el almacenamiento en caché a nivel del servidor está activado. Si recibe el mensaje "El almacenamiento en caché del servidor está desactivado", entonces algo anda mal.

No olvide eliminar esa adición del archivo wp-config.php , y también elimine la publicación ficticia cuando haya terminado. Fantástico: hemos configurado el almacenamiento en caché, todas las páginas ahora se sirven directamente desde los archivos HTML en caché estáticos, omitiendo PHP y WordPress.

Agregar CDN

Aunque la KB ya está en muy buen estado, cada vista de página desde un nuevo navegador "golpeará" nuestro servidor. Por lo tanto, quiero eliminar eso agregando una capa más: CDN.

Los beneficios claros de CDN son la distribución de centros de datos globales, la alta disponibilidad y una disminución masiva de los recursos del servidor, especialmente cuando las cosas son estáticas. Las páginas se cargarán directamente desde la CDN sin siquiera "tocar" nuestros servidores.

No puedo hablar lo suficiente de CloudFlare. Hemos estado usando su CDN (y sus extras) durante años, y lo que es una locura en todo esto: ¡puedes usarlo gratis! Eso es correcto: absolutamente gratis para el 95% de sus funciones.

Solo para darle un ejemplo, supongamos que tiene una página estática popular en el sitio que recibe 5 millones de visitas únicas diarias. Ignorando los servidores proxy y el almacenamiento en caché de ISP, esto generaría al menos 5 millones de visitas diarias a su servidor. Cuando usa un CDN como CloudFlare, esta página estática solo se cargará desde su sitio unas pocas veces al día (según la frecuencia de depuración del caché de CDN).

Aquí hay algunas estadísticas reales de un subdominio que solo sirve imágenes:

Mire esos números: ahorramos más de 600 GB de ancho de banda para nuestros servidores. Si configura WordPress + WP Super Cache Plugin + Server Level Caching + CloudFlare CDN, ¡probablemente pueda usar una gota de DigitalOcean de $ 5 / mes sin ningún problema de escala!

Hagamos algunos cálculos juntos... WordPress es gratis, WP Super Cache es gratis, CloudFlare CDN es gratis... Ah, solo cuesta $5 al mes para WordPress escalable. Loco, ¿verdad?

¿Cómo personalizamos la búsqueda de KB para servir datos almacenados en caché?

De forma predeterminada, la estructura de enlaces permanentes de búsqueda de WordPress utiliza un parámetro de cadena de consulta s= para pasar la consulta de búsqueda. Por una buena razón, WP Super Cache ignora las cadenas de consulta. Por lo tanto, tuvimos que hacer algunos pequeños ajustes en la estructura de las URL de búsqueda para que funcionara:

Esta actualización cambia la estructura de URL a freemius.com/help/documentation/search/{query}/ que se almacena en caché en WP Super Cache.

¡Auge! Incluso nuestros resultados de búsqueda se almacenan en caché ahora.

¿Cómo aseguramos nuestra base de conocimientos de WordPress?

La seguridad es una clave. Lo último con lo que cualquier empresa, especialmente una startup, quiere lidiar es con una brecha de seguridad. Puede dañar su reputación, arriesgar su IP (Propiedad Intelectual) y quitarle horas, a veces incluso días, para recuperar el control y los datos.

A muchos desarrolladores les encanta hablar mal de WordPress y decir que es inseguro. Según los números, sí, probablemente tengan razón. Dado que WordPress es la plataforma web más popular, también es el objetivo número 1 para los piratas informáticos, y los números tienen sentido: Duh...

Lo que no entienden es que WordPress como plataforma es probablemente uno de los proyectos más seguros. Las vulnerabilidades provienen principalmente de versiones antiguas y desactualizadas de WordPress, complementos y temas de terceros, y de usuarios que configuran contraseñas débiles.

So the first thing we would like to do is eliminate any notion of WordPress in our source code to reduce the chances of an attack.

1. WordPress adds a bunch of (mostly) unuseful metadata to the head of every page which is pretty much unique to WordPress, let's get rid of that by adding the following code to the theme's functions.php file:

2. Many WordPress plugins add HTML comments with a unique thumbprint that are easily identified. For example, Yoast SEO adds the following code:

<!-- This site is optimized with the Yoast SEO plugin v3.7.0 - https://yoast.com/wordpress/plugins/seo/ -->

That makes it easy for attackers to identify the site as WordPress.

Remember CloudFlare?

It has a checkbox to automatically minify HTML and get rid of all the HTML comments added by different plugins, themes and WordPress core:

¡Hecho!

3. Another known identifier of WordPress is the /wp-admin/ path to the login page. We installed WPS Hide Login, and configured our own “secret” path to the login page.

Assuming you set your login to your-site.com/my-secret-login/ make sure you add that path to WP Super Cache exclusion list. You can find it under WP Admin → Settings → WP Super Cache → Advanced:

Otherwise, it might mess up things when using SSL.

4. No need to mention – you and your team should be keeping your passwords strong! You can use a plugin like Force Strong Password to enforce a 'strong passwords' policy.

5. Force your login and WP Admin browsing via HTTPS to prevent password sniffing. You can achieve that by adding the following defines to the wp-config.php file:

define('FORCE_SSL_ADMIN', true);
define('FORCE_SSL_LOGIN', true);

6. One of the most popular attacks on WordPress sites is Brute force attack. Having a strong password policy helps, but can't really protect against it. Thus, we installed Google Captcha plugin that adds a simple captcha validating it's a human being:

Also, we installed Login Watchdog, a lightweight plugin that automatically bans suspicious IPs after pre configured amount of failed logins.

And if you are using CloudFlare as I recommended, it comes with a security layer against any threats, and since it's widely used, it has a “network knowledge” to protect your site from IPs that were attacking other sites powered by CloudFlare.

7. You should also secure WordPress on the server layer, preventing direct access to files like wp-login.php , hiding sensitive files, etc. Just follow this post:
https://lamosty.com/2015/04/14/securing-your-wordpress-site-running-on-nginx/

So yes – as long as there is a login page to our WordPress, it would never be secure as a pure static website. But the fact that we have turned our KB's frontend to static, hidden any evidence that we are using WordPress, added brute force protection and forced the login via HTTPS with a strong password policy, makes it very very (very) hard to hack.

I would dare to say that the only way the Knowledge Base will be hacked is if a security dojo will target our site specifically (that's rare, and I'm NOT calling anyone for a challenge).

Now you

Hopefully, this (very) elaborate article/tutorial will be useful for you when you come to make the important decision of what to go with for your knowledge base documentation solution.
No doubt, there's a lot to take into account here, and many of the decisions we made were influenced by our very specific needs & desires.

You could either copy & paste the entire process and customizations, or go deeper and customize it according to your specific needs. What's more important is to grasp the line of thought that lead the decision making and choosing & picking what's right for us. It was not easy because as I've shown – there are quite a few viable options out there, however, it did pay off, as Freemius now has an awesome Knowledge Base center, which is super customizable, lightning fast and scalable!

Hope you have a clear view how you can get started implementing and setting up your own documentation solution.

¡Buena suerte!