Shulou(Shulou.com)06/02 Report--

This article mainly introduces how to use Docsify and GitHub Pages to create a documentation website, the article is very detailed, has a certain reference value, interested friends must read it!

Create a document web page using Docsify and publish it to GitHub Pages.

Documentation is an important part of helping users use open source projects, but it is not always a priority for developers, because they may be more concerned with making their applications better than helping people use it. This is why it is so valuable for developers to make it easier to publish documents. In this tutorial, I'll show you a way to do this: combine the Docsify document generator with GitHub Pages.

By default, GitHub Pages prompts users to use Jekyll, a static site generator that supports HTML, CSS, and other web technologies. Jekyll can generate a static Web site from a document file encoded in Markdown format, and GitHub automatically recognizes their .md or .markdown extensions. Although this setting is good, I'd like to try something else.

Fortunately, GitHub Pages supports HTML files, which means you can use other site generation tools (such as Docsify) to create a website on this platform. Docsify is an open source project licensed under the MIT license that allows you to easily create an attractive, advanced documentation website on GitHub Pages.

Docsify

Start using Docsify

There are two ways to install Docsify:

Hongmeng official Strategic Cooperation to build HarmonyOS Technology Community

Install the command line interface (CLI) of Docsify through NPM.

Write your own index.html manually.

Docsify recommends using NPM, but I will use the second option. If you want to use NPM, follow the instructions in the Quick start Guide.

Download sample content from GitHub

I have posted the source code for this example on the GitHub page of the project. You can download these files individually, or you can clone the repository in the following ways.

Git clone https://github.com/bryantson/OpensourceDotComDemos

Then cd enters the DocsifyDemo directory.

I'll introduce you to this code below, which is cloned into my sample repository so that you can understand how to modify Docsify. If you prefer, you can also create a new index.html file from scratch, just like the example in the Docsify document:

Window.$docsify = {/ /...} explore how Docsify works

If you clone my GitHub repository and change it to the DocsifyDemo directory, you should see this file structure:

File contents in the cloned GitHub

File / folder name content index.html the main Docsify initialization file and the most important file _ sidebar.md generates navigation README.md the default Markdown file in your document root images contains examples in README.md .jpg pictures other directories and files contain navigable Markdown files

Index.html is the only requirement that Docsify can work. Open the file and you can view its contents:

Docsify Demo window.$docsify = {el: "# app", repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo', loadSidebar: true,}

This is essentially a normal HTML file, but look at these two lines:

... Something else.

These exercises use the URL of the content delivery Network (CDN) to provide CSS and JavaScript scripts to convert the site into a Docsify site. As long as you include these lines, you can turn your normal GitHub page into a Docsify page.

The first line after the label specifies what to render:

Docsify uses a single-page application (SPA) to render the requested page instead of refreshing a completely new page.

Finally, take a look at the lines in the block:

Window.$docsify = {el: "# app", repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo', loadSidebar: true,}

In this block:

The el attribute basically says, "Hey, this is the id I'm looking for, so find it and render it there."

Change the repo value to determine which page the user will be redirected to when he clicks the GitHub icon in the upper right corner.

Setting loadSideBar to true causes Docsify to look for the _ sidebar.md file that contains navigation links.

You can find all the options in the configuration section of the Docsify document.

Next, look at the _ sidebar.md file. Because you set the value of the loadSidebar attribute in index.html to true, Docsify looks for the _ sidebar.md file and generates a navigation file based on its contents. The contents of the _ sidebar.md in the sample repository are:

* [HOME] (. /) * [Tutorials] (. / tutorials/index) * [Tomcat] (. / tutorials/tomcat/index) * [Cloud] (. / tutorials/cloud/index) * [Java] (. / tutorials/java/index) * [About] (. / about/index) * [Contact] (. / contact/index)

This uses Markdown's link format to create navigation. Note that links such as "Tomcat", "Cloud", and "Java" are indented; this means that they are rendered as child links under the parent link.

Files like README.md and images are related to the structure of the repository, but all other Markdown files are related to your Docsify page.

Modify the files you download according to your needs. Next, you will add these files to your GitHub repository, enable GitHub Pages, and complete the project.

Enable GitHub pages

Create a sample GitHub repository, and then check out, submit, and push your code using the following GitHub command:

$git clone your GitHub repository location $cd your GitHub repository location $git add. $git commit-m "My first Docsify!" $git push

Set up your GitHub Pages page. In your new GitHub repository, click "Settings":

Settings link in GitHub

Scroll down until you see "GitHub Pages":

GitHub Pages settings

Find the "Source" section:

GitHub Pages settings

Click the drop-down menu under "Source". Usually, you will set it to "master branch", but you can also use other branches if you like:

Setting Source to master branch

okay! You should now have a page that links to your GitHub Pages. Clicking this link will take you there and render it with Docsify:

Link to GitHub Pages docs site

It should look like this:

The above is all the content of the article "how to use Docsify and GitHub Pages to create a documentation website". Thank you for reading! Hope to share the content to help you, more related knowledge, welcome to follow the industry information channel!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.