Skywalking: Using Hugo to refactor Apache SkyWalking's website

[rootsongjc]

• Why do you submit this issue?
• [ ] Question or discussion
• [ ] Bug
• [x] Requirement
• [ ] Feature or performance improvement

I propose using Hugo to refactor SkyWalking's site, the current site is not user friendly in terms of content organization, and more importantly, the documentation is not put together with the site, you need to jump to GitHub to read the documentation.

I created a prototype of the new website using Hugo, as shown below.

Sections can also be added and customized on the home page. The menu can also be modified. The entire website will be rebuilt in two phases:

• the first phase migrating the current website to Hugo
• the second phase migrating the documentation to Hugo

Hopefully someone will come along and work with me to refactor the site and make the experience of contributing to SkyWalking and browsing the website more friendly.

[kezhenxu94]

and more importantly, the documentation is not put together with the site

You can build the doc into the website, but if you want to separate the docs parts into the website repo, it's not recommended because we prefer to update the docs together with the codes if any

By the way, there is a rework of the website in progress by a student in the summer code activity mentored by @wu-sheng , maybe you need to wait for that to continue you refactoring?

[wu-sheng]

Jimmy had pinged me about this. The progress of the student is far away of what we expected. I would say we could ignore that part.

With our discussion, doc will be kepy where they are today. Jimmy should be able to use CI process to bind the required tagged and master branch doc.

[rootsongjc]

The documentation will remain in the code, it will just be integrated as the site is built, but the documentation in the code will need to be modified to Hugo's format.

[rootsongjc]

Now you can see the preview of the new site from https://skywalking.netlify.app/. This site is built from rootsongjc/skywalking-webiste.

All of the English pages have been migrated to the new website.

Here are the plans for the three-phase of the new website.

Phase I

Home page

1. The SkyWalking logo is missing from the navbar, it works on my local computer 😂
2. Add some more sections: latest events, blogs, and end-users brands
3. Adjust the color scheme to meet the SkyWalking culture
4. Change the background image @wu-sheng could you add more details about what do you like the design or the home page?
5. Mobile adaptIon

Blog

1. Modify the display elements of the list to add information such as author and tag.
2. Set the scheme information for the blog(this will be used on every blog post markdown header config)

Events

1. Adjust the page layout of a single evnet and fix display errors in the sidebar.

Team & Downloads

1. Adjust the layout, some part of the text are covered up.

Phase II

1. Multi-language support
2. Migrate some blog posts to the website Github repo to test the layout

Phase III

1. Integration test with the SkyWalking main repository
2. Setup the automation

@Fine0830 Could you help for the UI design and layout of the new website?

[wu-sheng]

@rootsongjc Also, we need to add Google/Baidu Analyse to set statistics for the browser as we are moving more things on it. It will help us to know the scope of our community.

The username and password of those platforms should be sent to [email protected](private mail list). Please ping me before you sent, that mail list requires me manual check for receiving mail from no-PMC members.

[rootsongjc]

@wu-sheng Hugo has built-in Google Analytics, to enable it. Do you mean to say create a separate Google Analytics account for this site? Who will turn on Google Analytics, and so will Baidu Tongji.

[wu-sheng]

Is Google Analyze able to track Chinese user access? Or we have to set up Baidu Tongji as a backup.

I could create accounts for the project. Do you have the links for creating both?

[rootsongjc]

Is Google Analyze able to track Chinese user access? Or we have to set up Baidu Tongji as a backup.

I could create accounts for the project. Do you have the links for creating both?

Google Analytics tracking is available in China. But to be on the safe side, you can also configure both traces at the same time.

• Google Analytics: https://analytics.google.com/analytics/web/
• Baidu tongji: https://tongji.baidu.com/web/welcome/login

[wu-sheng]

I have sent you invitations for both platform. If anyone else wants the invitation, please ping me.

[heyanlong]

hi, @rootsongjc great work, far all I know, hugo cannot provide a perfect search solution, how to solve?

[rootsongjc]

There are two solutions:

• Google custom search: this is easy to integrate, but not accessible in China
• Algolia: need to do some works to integrate it, you can see the live effect on my own blog

[rootsongjc]

Sorry for updating so late. I need help on the front-end and UI side.

I'll start by listing the current front-end issues with the SkyWalking website that was rebuilt using Hugo, and we'll cover the other sections that need to be added later.

Here's a list of issues by page.

Homepage

Mobile adaptation: let that architecture diagram be adaptive to the page width.

Blog, event page

Function request: Image click to enlarge full screen (lightbox function)

Optimization: remove the sidebar on the right side of the "edit document" and "create issue", so that the entire blog and activity list occupy the entire width of the page.

Team, download page

Optimization: typography problems, CSS changes to be made

The text is above the header.

[wu-sheng]

@Jtrust Please help @rootsongjc when you have time. I hope the update could be done before DevCon, 14th Nov.

[Jtrust]

@Jtrust Please help @rootsongjc when you have time. I hope the update could be done before DevCon, 14th Nov.

With pleasure

[rootsongjc]

All of the layout issues have been fixed, there‘re some problems left:

• [x] P0: the logo of SkyWaling with SVG is missing. See the above image, it the SVG not works, we can use PNG type instead
• [x] P1: migrate the Docs and GitHub tabs into Documentation on the menu, the Documentation page will look like this: https://www.sofastack.tech/projects/, as there are a lot of sub-projects of SkyWalking, we should list the portals of the docs from different projects on the single page
• [x] P2: [WIP] update the layout of the download page, to allow the download addresses of different projects to be flattened on the page using modules.
• [x] p0: homepage scroll bar error (mobile end adapt)
• [x] P1: multi-language support issue, Chinese pages cannot be displayed, it is located at content/zh folders
• [x] P1: the text can not be displayed at the language switch button
• [x] P2: display the Apache trademark text Apache SkyWalking, SkyWalking, Apache, the Apache feather logo, and the Apache SkyWalking project logo are either registered trademarks or trademarks of the Apache Software Foundation. at the footer
• [x] P1: fix the blank Chinese homepage
• [x] P0: 中文博客 tab is missing at the sidebar of the homepage in mobile view
• [x] P1: There are problems with the color scheme of some of the codes. The white font and white background make it unreadable. See here
• [x] P1: Features section of homepage
• [x] P1: "Who is using SkyWalking" section of the homepage, just links the current state of SkyWalking website. For now, we can start with one image, in the future, we will need to lay out all the logos flat.
• [x] P1: Events & News section of homepage

[rootsongjc]

The logo problem has been fixed, I used a PNG image to replace the SVG one.

[rootsongjc]

The homepage scroll error fixed. We'd fix the language switch button now.

[rootsongjc]

After confirming with @wu-sheng that SkyWalking's website does not need to support multiple languages, I removed the language switch button. Just leave the English pages. There will be a tab on the header named 中文博客, all of the Chinese blogs will be archived there which will reuse the blog layout. You can see the preview at https://skywalking.netlify.com, I will move the legacy Chinese blogs to the new site steps by steps. I will finish it tomorrow.

[wu-sheng]

Thanks, @rootsongjc. It is great to see things are getting ready.

[rootsongjc]

The first version is basically finished, but there are still some problems left, which we can fix slowly. I will submit a PR.

The next issues to be fixed in the next version include:

• [x] P2: update the layout of the download page, to allow the download addresses of different projects to be flattened on the page using modules.
• [x] P2: Events & News section of the homepage, we should make it auto-generated, display the latest 4 events from the event lists
• [ ] P1: Migrate the documentation, version support needed
• [ ] P2: Make the projects and documentation page configurable, use the YAML or markdown instead of the raw HTML
• [x] P1: fix the footer display problem
• [ ] P2: add an arrow on the homepage, jump to the below sections
• [x] P2: add screenshots on the homepage
• [ ] P1: add table of content on the blog page

[wu-sheng]

In the next iteration, I prefer to add screenshots review on the homepage.

[wu-sheng]

Here, I want to update the progress. @Jtrust did a lot of works to help to make the website better and fancy.

• [x] P2: update the layout of the download page, to allow the download addresses of different projects to be flattened on the page using modules.
• [x] P2: Events & News section of the homepage, we should make it auto-generated, display the latest 4 events from the event lists
• [ ] P1: Migrate the documentation, version support needed
• [x] P2: Make the projects and documentation page configurable, use the YAML or markdown instead of the raw HTML
• [x] P1: fix the footer display problem
• [x] P2: add an arrow on the homepage, jump to the below sections
• [x] P2: add screenshots on the homepage
• [x] P1: add table of content on the blog page

The only one thing left is the doc page generation.

[Fine0830]

Wow! That's totally awesome!

[wu-sheng]

The last piece is going to be added through https://github.com/apache/skywalking-website/pull/215.
@Jtrust are doing great with this long and complex task. We are going to have the main doc hosted on the website soon, maybe today or tomorrow.