foreword
Some time ago, I planned to make a homepage for my open source project. On the one hand, a good facade can increase the attention of the project, and on the other hand, it can integrate the resources involved in the project.
In fact, the original project already has a document homepage, which is relatively simple and generally looks like this:
It actually looks okay, doesn't it?
This is done with docsify. docsify is an excellent document generation tool. It is relatively simple to use. You only need to write the markdown file of the content. It supports most of the syntax of markdown, and also extends some of the syntax display effects.
But I think that although docsify is not bad for building documents, it is a bit shabby for building project homepages. First of all, its positioning is a documentation tool, and secondly, the theme style is not rich enough, and the customization of the page is relatively poor, just such a routine. I have so few requirements for static website builders
- Rich themes, beautiful and simple. After all, the project homepage is the facade of a project, and it is very important to look good.
- The construction is simple, and I only focus on the content part as much as possible, because after all, I am not proficient in front-end, and I don’t want to learn a lot of front-end knowledge in order to build a homepage.
- The homepage needs to be well-organized and have the sense of sight of the homepage of a large project.
- Page customization is strong and cannot be stereotyped.
- Can maximize the integration of resources, multi-level directory.
Static website generator
With these requirements in mind, I compared common static site generators today. In the end, I decided to choose Hexo, VuePress, and Docusaurus.
After careful comparison of the function points, I finally chose Docusaurus because of its good looks.
Of course, appearance is an important part, and the second reason is that Hexo is bad, and I personally feel that it is not suitable to be an open source project homepage. Although VuePress is also very good, and Chinese support is also very good, but I am not too proficient in Vue, so I chose to give up.
Docusaurus is a static site generation framework open sourced by Facebook. It is relatively new, and many people in China may not necessarily know it. But many of Facebook's new open source project sites are now using Docusaurus.
This is the Docusaurus official website home page:
Docusaurus is built on React. Basically, it can meet my requirements for the homepage of the project, and the degree of customization is relatively high. The disadvantage is that the Chinese support of the documentation is not very good. Although Docusaurus1 has built a Chinese site, the documentation is only partially translated, not fully translated. Docusaurus2 is full of English documents. Read on, though, and it should be easy to figure out what to do.
Homepage process
Let’s not talk nonsense first, let’s put the final effect and link of the homepage after I built it with Docusaurus for everyone to observe:
The project homepage link is:
Isn't it kind of like that? Now that you have clicked, please help me to star this open source project on gitee&github.
Below I will describe the process of building a homepage.
Docusaurus requires pre-installed node.js and yarn, and requires node.js version 10.15.1 and above, and yarn version 1.5 and above
You can create an initial project site by scaffolding:
npx @docusaurus/init@next init my-website classic
Once created, you can enter your project and run
yarn run start
Enter 127.0.0.1:3000 in your browser and you will see the following initialization site:
Of course, I didn't change it on the site created by scaffolding. I chose a site from the display site on the official website, and then downloaded their source code to compile and start. Then make changes based on it.
Overall, the configuration of Docusaurus is fairly simple, and the home page can be customized to a high degree. If you are proficient in react, you can play cool tricks. If you are not proficient in react, you can also modify it according to other people's source code, and you can get a similar effect. For specific configuration documents, you can refer to the Chinese site of Docusaurus:
The documentation section here has Chinese translations.
The rest of the work is to edit markdown. Docusaurus has made many extensions to the features of markdown, which is my favorite part. With these extensions, you can edit beautiful documents.
My favorite markdown extensions are:
Tab：
Docusaurus supports embedding tab tags in documents. The specific effects are:
Hignlight block:
Docusaurus extends the syntax of markdown, so that highlight blocks of different colors can be displayed in the document according to their importance. The specific effect is:
Highlighted line of code:
I believe many people have used the code block in markdown, it is very convenient, and it can also be colored according to the code. But if you want to highlight a few lines of code, what should you do? The default syntax of markdown is impossible. Docusaurus extends this feature, and the effect is as follows:
If there are multiple lines, you can also define it like this: {1,4-6,11}, so that the first line, 4 to 6 lines, and 11 lines will be highlighted.
In addition to the above three features that I prefer, Docusaurus also provides very detailed extensions, I believe these are all useful for you.
About the project home page
The main color of my open source project homepage is black and gold, so I made some changes to the color of css and tried to keep it as a whole, including icon color, logo color, and image color in the document, all of which are unified. Therefore, it is recommended to choose the color scheme in the early stage of building the homepage. More colors may not necessarily look comfortable. Simple and unified is a better choice.
Some friends asked: Where did your Logo come from, did you design it yourself?
I don't do graphic design, this should be done by professionals. This logo cost hundreds of dollars to hire someone to design. I think an open source project should also convey its own brand message. So it's worth it.
About open source projects
TLog is a new open source project. It is currently one of the main maintenance and iteration projects in my open source projects. It is mainly dedicated to the tracking of logs in a distributed environment. It is small and easy to use, and the community is very active. Since it was open sourced for a month, I have received feedback from many people, and listened to these feedbacks to iterate and develop new features.
The future blueprint of TLog is to make the log domain collection, tracking, statistics, analysis, and display in one log middleware.
The Gitee official has carried out community promotion on TLog, and the official has issued a document to promote:
Now that TLog has its own official website homepage, I will continue to iterate on this open source framework in the future. I hope everyone will pay attention. If you like it, please help and give the project a star.
Follow the author
"Yuanren Tribe" is a technology sharing account that insists on being original. I hope you can pay attention to me. I will publish a practical original technical article every week to walk with you and grow with you. Follow the official account to reply tlogto join the group chat, I will patiently answer every question you have in use, and will also maintain and iterate on this project for a long time.
