Una pequeña herramienta de menos de 10 MB para proporcionar acceso local y rápido a documentos para mejorar la mala experiencia de lectura de documentos en línea durante el proceso de desarrollo.
Además, presente cómo crear rápidamente un conjunto de herramientas de documentos fuera de línea que sea propicio para su distribución y uso.
escribir delante
Aunque ahora hay muchos productos de codificación asistida por IA y Chat Bot, y la experiencia de escribir código se ha vuelto muy buena, en el proceso de codificación diario, inevitablemente necesitamos leer los documentos de los productos de código abierto.
Por varias razones, incluida la experiencia de acceso a los documentos implementados en GitHub Pages, es difícil de describir. Al navegar por documentos, el navegador gira en círculos de vez en cuando, lo que afecta en gran medida el pensamiento continuo y es una pérdida de tiempo.
Especialmente en el artículo " Es posible que su sitio web no necesite una construcción front-end (2) ", mencioné varios marcos y herramientas front-end muy buenos, y todos sus documentos están alojados en GitHub.
Además, simplemente descargar estos documentos localmente no resuelve completamente el problema del acceso lento, porque los documentos también pueden hacer referencia a algunas interfaces API externas o widgets de Internet. Antes de cargar estos widgets, la página puede ser "Páginas blancas".
Por lo tanto, combinado con el artículo " Improving the Static Middleware of the Golang Gin Framework: Gin-Static " de principios de este año, creé una pequeña herramienta para proporcionar acceso rápido y local a documentos para mejorar la mala experiencia de leer documentos en línea durante el proceso de desarrollo. . .
El proyecto es de código abierto en soulteary/docker-quick-docs . Puedes conectarte con un clic u obtener el código que necesitas.
Convierta documentos en línea a documentos locales
Tomamos el documento en línea implementado por baidu/san en GitHub Pages como ejemplo para convertirlo en un documento local al que se puede acceder rápidamente.
Obtener datos del documento
El contenido similar a este proyecto implementado en GitHub Pages generalmente está en gh-pagesla rama del proyecto, por lo que tenemos dos formas de obtener el contenido del documento: la primera es cambiar la rama del proyecto a la página gh-pagesy luego hacer clic en el botón para descargar el código. , obtenga el paquete comprimido del código fuente.
Sin embargo, es más problemático para nosotros actualizar el contenido del código de esta manera, por lo que recomiendo el segundo método, usando git cloneparámetros de transporte para descargar el código del directorio especificado y haciéndolo lo menos posible clone:
git clone http://github.com/baidu/san --depth 1 --branch=gh-pages
Una vez ejecutado el código, podemos obtener datos de documentos actualizables del almacén con relativa rapidez:
# git clone http://github.com/baidu/san --depth 1 --branch=gh-pages
Cloning into 'san'...
warning: redirecting to https://github.com/baidu/san/
remote: Enumerating objects: 405, done.
remote: Counting objects: 100% (405/405), done.
remote: Compressing objects: 100% (197/197), done.
remote: Total 405 (delta 154), reused 303 (delta 65), pack-reused 0
Receiving objects: 100% (405/405), 2.17 MiB | 5.18 MiB/s, done.
Resolving deltas: 100% (154/154), done.
Si deseas actualizar el código más adelante, solo necesitas ingresar al directorio y ejecutar git pull:
# cd san
# git pull
Already up to date.
Iniciar documentos rápidos
Hay dos formas de utilizar Quick Docs: una es descargar el archivo binario adecuado para su sistema desde la página de lanzamiento de GitHub y luego ejecutarlo directamente.
./quick-docs
De forma predeterminada, creará automáticamente docsun directorio en el directorio y guardará todos los documentos que hemos preparado en este directorio para que podamos tener una experiencia local.El puerto predeterminado es 8080.
Si desea ajustar el puerto, puede configurar las variables de entorno en el comando PORT. Por ejemplo, si desea ejecutar en 9000el puerto, podemos hacer esto:
PORT=9000 ./quick-docs
Por supuesto, si eres un entusiasta de Docker, tenemos una solución más “verde”:
# 下载工具
docker pull soulteary/docker-quick-docs:v0.1.2
# 使用工具启动文档
docker run --rm -it -v `pwd`/docs:/app/docs -p 8080:8080 soulteary/docker-quick-docs:v0.1.2
Cuando el programa complete la ejecución, podremos ver un resultado similar al siguiente:
2024/01/04 11:39:54 Quick Docs v0.1.2
En este momento, cuando visitamos, http://localhost:8080podemos ver qué directorios se pueden explorar.
Debido a que solo almacenamos sanlos documentos de un proyecto, después de abrir el navegador, por el momento solo tenemos acceso a este directorio. Si desea acceder a más documentos, simplemente coloque los diferentes documentos en docsel directorio e inicie el programa.
Haga clic en el directorio y podremos ver sanla documentación de implementación local:
A diferencia de GitHub, que es lento, la velocidad de acceso a los documentos implementados localmente se ha mejorado significativamente. Si accede con frecuencia a documentos de cierto software de código abierto, esta solución definitivamente puede ahorrarle mucho tiempo.
En circunstancias normales, después de este paso, se ha completado el acceso localizado al documento. Sin embargo, creo que si buscas lo último, debes esperar que la página local se pueda abrir más rápido o incluso que sea completamente accesible sin conexión, así que sigamos lanzando.
Funciones avanzadas: reescritura del contenido del documento
Sigamos tomando sanel documento de como ejemplo, abrimos la herramienta de depuración de red y actualizamos la página nuevamente, podemos ver que hay dos solicitudes obvias que se cargan lentamente.
Para solucionar este problema, podemos utilizar la "función de reescritura de contenido" admitida por la herramienta.
reescritura simple
Tomando el contenido anterior como ejemplo, las direcciones de solicitud más lentas en la página anterior son:
https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css
https://ghbtns.com/github-btn.html?user=baidu&repo=san&type=star&count=true&size=large
Por ejemplo, podemos reescribir la solicitud anterior como "vacía" para evitar solicitudes lentas:
[
{
"from": "https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css",
"to": ""
},
{
"from": "https://ghbtns.com/github-btn.html",
"to": "about:blank"
}
]
Guardamos el contenido anterior como config.json, si usa un archivo ejecutable para ejecutar el programa y luego reinicia el programa, el programa cargará y aplicará automáticamente el archivo de configuración.
Si es un usuario de Docker, debemos ajustar el comando para asignar este archivo de configuración al contenedor:
docker run --rm -it -v `pwd`/docs2:/app/docs -v `pwd`/config.json:/app/config.json -p 8080:8080 soulteary/docker-quick-docs:v0.1.2
Cuando el programa complete la ejecución, veremos un resultado similar al siguiente:
2024/01/04 12:06:57 Quick Docs v0.1.2
2024/01/04 12:06:57 未设置环境变量 `PORT`，使用默认端口：8080
2024/01/04 12:06:57 解析配置文件成功，规则数量: 2
En este momento, abra la página nuevamente y actualice la página web. Podemos ver que todas las solicitudes provienen de local y sentimos que la velocidad de solicitud de la página es más rápida.
Puede colocar tantos documentos en docsel directorio como desee para mejorar su experiencia de lectura de documentación de desarrollo.
Reescritura de mayor rendimiento
Sin embargo, si tenemos muchos directorios de documentos y muchas reglas de reescritura, definitivamente causará una pérdida innecesaria de rendimiento, incluso si el programa en sí es lo suficientemente simple y el rendimiento del hardware moderno es lo suficientemente alto.
Pero si Quick Docs se ejecuta en una computadora portátil que funciona con batería o en un host pequeño de un solo núcleo, puede guardarlo si puede.
Solo necesitamos agregar el campo debajo de las reglas de reescritura anteriores dirpara limitar el alcance efectivo de las reglas de reescritura. Si desea restringirlo aún más, también puede establecer el tipo de contenido reescrito type:
[
{
"from": "https://ecomfe.github.io/san/",
"to": "/san/",
"type": "html",
"dir": "/san/"
},
{
"from": "https://github.com/baidu/san-router",
"to": "/san-router/"
},
{
"from": "https://ecomfe.github.io/santd/",
"to": "/santd/"
}
]
De forma predeterminada, si no configuramos diro type, el programa tendrá efecto en los archivos de todos los directorios html.
Los tipos de archivos admitidos actualmente incluyen html, js, css, json, que deberían ser suficientes para una estación de documentos sin conexión, ¿verdad? Si cree que no es suficiente, puede expresar sus opiniones en el tema del proyecto.
Bueno, si tiene muchos documentos que deben alojarse localmente, ver esto es suficiente para solucionarlo.
Construir documentación de un solo programa para su distribución.
Al comienzo del documento, mencioné cómo crear un conjunto de herramientas de documentación fuera de línea que sea conveniente para su distribución. Se trata principalmente de la capacidad de reutilizar el middleware del artículo anterior " Mejora del middleware estático del marco de Golang Gin: Gin-Static ".
Para crear un kit de herramientas sin conexión de un solo archivo, primero debemos descargar el código del proyecto:
git clone https://github.com/soulteary/docker-quick-docs.git
Luego, como arriba, coloque los documentos que queremos solidificar en el programa docsen el directorio.
Ejecute el comando de compilación del programa:
go build -o quick-docs
Una vez ejecutado el programa, podemos obtener el programa con la documentación "integrada" en el directorio actual y ejecutarlo desde el docsdirectorio anterior.
Nuestro programa de documentos fuera de línea está listo, al ejecutarlo es necesario llevar un parámetro EMBED=onpara activar Embededla función:
EMBED=on ./quick-docs
No hay diferencia en el uso del programa como se mencionó anteriormente.
por fin
Bien, ahora que he escrito esto, se han introducido todos los usos de Quick Docs.
Nos vemos en el próximo artículo.
–EOF
Este artículo utiliza el acuerdo de licencia "Attribution 4.0 International (CC BY 4.0)". Puede reimprimirlo, modificarlo y utilizarlo, pero se debe indicar la fuente. Atribución 4.0 Internacional (CC BY 4.0)
Autor de este artículo: Su Yang
Hora de creación: 4 de enero de 2024
Recuento estadístico de palabras: 4924 palabras
Tiempo de lectura: 10 minutos
Enlace para leer este artículo: https://soulteary.com/2024/01/04/improving-the-github-pages-reading-experience- rápido -docs.html