Skip to content

Commit

Permalink
update ReadMe
Browse files Browse the repository at this point in the history
  • Loading branch information
@forchain
forchain committed Dec 21, 2021
1 parent 2397e3a commit 3a9b7f6
Showing 1 changed file with 116 additions and 56 deletions.
172 changes: 116 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,67 +1,86 @@
# docs
The Qitmeer documentation & guides and tutorials.
# Qitmeer Docs

# How To Run

### Mac
Qitmeer is an Open-Source community and welcome everyone to give contribution with their own talent. In addition to coding, documentation is also an important work to share knowledge with the community. Here are the steps how we share our expererience of Qitmeer.

#### download and install hugo
## Install Hugo

#### Prerequisite Tools
Qitmeer Docs is powered by Hugo static web generator, it could convert Markdown articles to HTML pages. Therefore, you could focus on content authoring and let Hugo handle website styling and management. Besides, the generated HTML pages are staic, which means they are secure and fast to load.

* [Git](https://git-scm.com/)
* [Go (at least Go 1.11)](https://golang.org/dl/)
You may install Hugo by budiling from source code.

#### Fetch from GitHub
```sh
$ mkdir $HOME/src
$ cd $HOME/src
$ git clone https://github.com/gohugoio/hugo.git
$ cd hugo
$ go install

Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of `GOPATH`, as in the following example:
$ hugo version
hugo v0.92.0-DEV darwin/amd64 BuildDate=unknown
```

Or follow this tutorial to install a prebuilt version.

https://gohugo.io/getting-started/installing

```bash
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install
## Depoit Qitmeer Docs locally

hugo version
Download source code and launch web server:

Hugo Static Site Generator v0.55.6/extended darwin/amd64 BuildDate: unknown
```sh
$ git clone https://github.com/Qitmeer/docs ~/github.com/Qitmeer/docs
$ cd ~/github.com/qitmeer/docs/Document
$ hugo serve
...
Web Server is available at http://localhost:1313/docs/ (bind address 127.0.0.1)
Press Ctrl+C to stop
```

#### Run
Open browser and test website is accesible. Address: **http://localhost:1313/docs/**

```bash
git clone https://github.com/qitmeer/docs.git
cd docs/Document/
![Launch Docs](/images/contribute-docs/launch-website.png)

hugo serve
> Figure1. Launch Qitmeer Docs
open http://localhost:1313/docs/
```
## New document file

# How To Add Document
We need to create a subfolder under the **content** folder and then new a file named **_index.en.md** inside it.

#### create a document item
You may complete those steps by one Hugo command:

```bash
hugo new content/example/_index.en.md
vim content/example/_index.en.md
```sh
# ensure you are under path ./Document
$ hugo new content/tutorials/contribute-docs/_index.en.md
```

> Note that all document files are placed under the content folder
#### Note:

1. the name of the subfolder must be in **hyphen-case** style, in this case, **"contribute-docs"**
1. the **en** part indicates the language, you may subsititue with other languages, for instance, **cn** stands for Chinese. Or you may drop this part to disable the multiple language support, then it would be like "**_index.md**"
2. The parts of the path are in line with the sitemap in the the left panel, for this case, this article is placed under **Tutorials** category.

![Doc category](/images/contribute-docs/doc-category.png)

> Figure 2. Doc category
### Add link in index page

There is an index page include all the links under each category, it is located at the parent folder of the containing folder of document, which is **content/tutorials/_index.en.md** for this tutorial.

#### Configuration page

```bash
hugo new content/nxtools/_index.en.md
vim content/nxtools/_index.en.md
```

Edit page parameters `content/nxtools/_index.en.md`
## Edit document

```bash
### Front Matter

From the file extension "**.md**", we could infer that it is a markdown document. Actually, it is an extented markdown file. We need to add some annoation in the front of the file, we could this **"Front Matter"**.

For this tutorial, it would be:

```markdown
---
title: NxTools
title: Contribute Qitmeer Docs

# Represents the sorting position of the sidebar
weight: 1
Expand All @@ -75,26 +94,67 @@ chapter: true
# This option needs to be set if the page has formula content
mathjax: true
---
```

The essential configuration item is "**title**", which is "**Contribute Qitmeer Docs**" in this case. You may modify other config items if needed, such as "**weight**", "**chapter**", ..., the comments above.

### content
### Markdown Content

Below the front matter separator '**---**', you may fill the content of articles with markdown format. For this tutorial as example, it would be:

```markdown
...
mathjax: true
---

Qitmeer is an Open-Source community and welcome everyone to give contribution with their own talent. In addition to coding, documentation is also an important work to share knowledge with the community. Here are the steps how we share our expererience of Qitmeer.

## Install Hugo
...
```

**Note:**

Hugo will insert the title configured in Front Matter, so we should **NOT** add title in the content.

### Images

The markdown is a text file and cannot embed images, therfore you should upload the images in a specified folder and add links to them.

For this tutorial, we already two figures. We make a folder under "**Document/static/images**", let's say "**contribute-docs**" for placing images dedicated to this tutorial, then move the images from their original folder to the newly created folder.

```sh
$ mkdir -p Document/static/images/contribute-docs
$ mv "/Users/Outlier/Library/Application Support/typora-user-images/image-20211218192001885.png" Document/static/images/contribute-docs/launch-website.png
$ mv "/Users/Outlier/Library/Application Support/typora-user-images/image-20211220190939112.png" Document/static/images/contribute-docs/doc-category.png
```

## Update github pages
At last, replace the image links with new path. Note, the path should be a website absolute path rather than a local path, leading by "**/image**".

### create gh-pages branch if doesn't exists
```bash
git checkout -b gh-pages origin/gh-pages
Therefore, find the two links in the file of this document:

```markdown
![Launch Docs](/Users/Outlier/Library/Application Support/typora-user-images/image-20211218192001885.png)
![Doc category](/Users/Outlier/Library/Application Support/typora-user-images/image-20211220190939112.png)
```
### update gh-pages
```bash
git checkout master
cd Document
hugo

cd ..
git checkout gh-pages
cp -rf Document/public/* ./
git add .
git commit -m"update YYMMDD"
git push

Replace them with respectively:

```markdown
![Launch Docs](/images/contribute-docs/launch-website.png)
![Doc category](/images/contribute-docs/doc-category.png)
```

## Submit documents

Qitmeer has a workflow to automate the tedious work of publishing in GitHub Pages, see:

https://github.com/Qitmeer/docs/blob/master/.github/workflows/gh-pages.yml.

Therfore, all you have to do is just submit the changes to Github and make pull request to the upstream branch.

```sh
$ git add .
$ git commit -m"contribute qitmeer docs"
$ git push
```

0 comments on commit 3a9b7f6

Please sign in to comment.