A small tool of less than 10MB to provide local and fast document access to improve the poor experience of reading online documents during the development process.
Also, introduce how to quickly create an offline document toolkit that is conducive to distribution and use.
write in front
Even though there are now a lot of AI-assisted coding and Chat Bot products, and the experience of writing code has become very good, in the daily coding process, we inevitably need to read the documents of open source products.
For various reasons, including the access experience of documents deployed on GitHub Pages, it is difficult to describe. When browsing documents, the browser spins in circles from time to time, which greatly affects the continuous thinking and is a waste of time.
Especially in the article " Your website may not need front-end construction (2) ", I mentioned a number of very good front-end frameworks and tools, and their documents are all hosted on GitHub.
Moreover, simply downloading these documents locally does not completely solve the problem of slow access, because the documents may also reference some external API interfaces or Internet widgets. Before these widgets are loaded, the page may be "White Pages".
Therefore, combined with the article " Improving the Static Middleware of the Golang Gin Framework: Gin-Static " earlier this year, I created a small tool to provide local and fast document access to improve the poor experience of reading online documents during the development process. .
The project is open sourced at soulteary/docker-quick-docs . You are welcome to connect with one click or get the code you need.
Convert online documents to local documents
We take the online document deployed by baidu/san on GitHub Pages as an example to turn it into a local document that can be quickly accessed.
Get document data
Content similar to this project deployed on GitHub Pages is usually on gh-pagesthe branch of the project, so we have two ways to obtain the document content. The first is to switch the project branch to the page gh-pages, and then click the button to download the code , get the source code compressed package.
However, it is more troublesome for us to update the code content in this way, so I recommend the second method, using git clonecarrying parameters to download the code of the specified directory, and doing it as little as possible clone:
git clone http://github.com/baidu/san --depth 1 --branch=gh-pages
After the code is executed, we can get updateable document data from the warehouse relatively quickly:
# 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.
If you want to update the code later, you only need to enter the directory and execute git pull:
# cd san
# git pull
Already up to date.
Start Quick Docs
There are two ways to use Quick Docs. One is to download the binary file suitable for your system from the GitHub release page and then execute it directly.
./quick-docs
By default, it will automatically create docsa directory in the directory, and save all the documents we have prepared in this directory, so that we can have a local experience. The default port is 8080.
If you want to adjust the port, you can set the environment variables in the command PORT. For example, if you want to run on 9000the port, we can do this:
PORT=9000 ./quick-docs
Of course, if you are a Docker enthusiast, we have a more “green” solution:
# 下载工具
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
When the program completes execution, we will be able to see output similar to the following:
2024/01/04 11:39:54 Quick Docs v0.1.2
At this time, when we visit, http://localhost:8080we can see which directories can be browsed.
Because we only store santhe documents of one project, after opening the browser, we only have access to this directory for the time being. If you want to access more documents, just put the different documents into docsthe directory and start the program.
Click on the directory and we will be able to see santhe local deployment documentation:
Unlike GitHub, which is slow, the access speed of locally deployed documents has been significantly improved. If you often access the documents of certain open source software, this solution can definitely save you a lot of time.
Under normal circumstances, after this step, localized access to the document has been completed. However, I believe that if you pursue the ultimate, you must hope that the local page can be opened faster, or even completely accessible offline, so let’s continue to toss.
Advanced features: document content rewriting
Let's continue taking santhe document of as an example. We open the network debugging tool and refresh the page again. We can see that there are two obvious requests that load slowly.
To solve this problem, we can use the "content rewriting function" supported by the tool.
simple rewrite
Taking the above content as an example, the slower request addresses in the above page are:
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
For example, we can rewrite the above request as "empty" to avoid slow requests:
[
{
"from": "https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css",
"to": ""
},
{
"from": "https://ghbtns.com/github-btn.html",
"to": "about:blank"
}
]
We save the above content as config.json, if you use an executable file to run the program, then restart the program, the program will automatically load and apply the configuration file.
If you are a Docker user, then we need to adjust the command to map this configuration file into the container:
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
When the program completes execution, we will see output similar to the following:
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
At this time, open the page again and refresh the web page. We can see that all requests come from local and feel that the page request speed is faster.
You can put as many documents in docsthe directory as you want to improve your development documentation reading experience.
Higher performance rewrite
However, if we have a lot of document directories and a lot of rewriting rules, it will definitely cause unnecessary performance loss, even if the program itself is simple enough and the performance of modern hardware is high enough.
But if your Quick Docs is running on a battery-powered laptop or a single-core small host, you can save it if you can.
We only need to add the field below the above rewrite rules dirto limit the effective scope of the rewrite rules. If you want to further restrict it, you can also set the type of rewritten content 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/"
}
]
By default, if we do not set diror type, the program will take effect on files in all directories html.
The currently supported file types include html, js, css, json, which should be enough for an offline document station, right? If you think it is not enough, you are welcome to put forward your opinions in the project issue.
Well, if you have a lot of documents that need to be hosted locally, seeing this is enough to deal with it.
Construct single-program documentation for distribution
At the beginning of the document, I mentioned how to create an offline documentation toolkit that is convenient for distribution. This is mainly about the ability to reuse the middleware in the earlier article " Improving the static middleware of the Golang Gin framework: Gin-Static ".
To make a single-file offline toolkit, we need to download the project code first:
git clone https://github.com/soulteary/docker-quick-docs.git
Then, as above, place the documents we want to solidify in the program docsin the directory.
Execute the program build command:
go build -o quick-docs
After the program is executed, we can get the program with "built-in" documentation in the current directory, and it can be run out of the previous docsdirectory.
Our offline document program is ready. When running, you need to carry a parameter EMBED=onto activate Embededthe function:
EMBED=on ./quick-docs
There is no difference in using the program as mentioned above.
at last
Okay, now that I have written this, all the uses of Quick Docs have been introduced.
See you in the next article.
–EOF
This article uses the "Attribution 4.0 International (CC BY 4.0)" license agreement. You are welcome to reprint, re-modify and use it, but the source must be indicated. Attribution 4.0 International (CC BY 4.0)
Author of this article: Su Yang
Creation time: January 4, 2024
Statistical word count: 4924 words
Reading time: 10 minutes
Link to read this article: https://soulteary.com/2024/01/04/improving-the-github-pages-reading-experience-quick -docs.html