Create a personal website (github pages) and host the site to Github with one click

Create a personal website (github pages) and host the site to Github with one click

Content: Use the website generator mkdocs to generate a wiki site from a markdown file and mount it to github Process summary Highlights
: One-click deployment of personal websites, simple documents are directly rendered into web pages and the entire process of mounting
Tools used: mkdocs and git commands

1、mkdocs：

  MkDocs is a fast, simple, and totally gorgeous static site generator for building project documentation. Documentation source files are python-based, written in Markdown format, and configured with a single YAML configuration file that can deploy the resulting website anywhere.

2. mkdocs installation:

  The linux system uses the command line to install:

sudo apt-get install mkdocs

  Since mkdocs is based on python, Windows users need to ensure that they have a python environment and pip tool, if not, go to the official website to download it.

  Windows users also go to the cmd terminal to install by running the following command:

pip install mkdocs

3. mkdocs version check:

mkdocs --version

  Under normal circumstances, if the installation is correct, you can see the version information of mkdocs

4. Create a wiki

(1) New project:

  Go to the appropriate documentation location and start creating your wiki

mkdocs new my_wiki

  Among them, my_wiki is the project name, which can be drawn up by yourself

  Go to the newly created project

cd my_wiki

  After the project is successfully created, you can see:

  There is a new folder my_wiki, and the folder docs is automatically generated in the folder to store md files. Here, a sample file index.md has been generated. In addition, there is a configuration file mkdocs.yaml for rendering web pages in the my_wiki folder

(2) Preview wiki

  Here we can actually preview the wiki page, enter the folder we just created, and enter the command in the terminal:

cd my_wiki
mkdocs serve

  After that, the following prompt will appear in the terminal:

  Copy the prompted URL information http://127.0.0.1:8000, paste it into the browser to see the preview information

  Exit the preview in the terminal and start editing our personalized website

ctrl+c

(3) Personalized modification editing

  The editor can choose to modify the original index.md according to the markdown syntax, or copy the md document that he has written to this path. When multiple md files coexist, they will be displayed side by side in the upper left corner and can be selected.

(4) Insert picture

   If you need to insert a picture, you can create a new imags (name can be customized) folder under the docs folder, and refer to the relative path of the picture according to the markdown syntax at the position where the picture needs to be inserted

![mkdocs](images/mkdocs.png)

  When inserting a picture, you must pay attention to the writing syntax of the relative path, especially if you copy it from an already written file, then there is a high possibility that there will be a problem, and the display is not normal. There may only be a small circle or a small box. This is most likely a relative path writing error.

• Writing a relative path as an absolute path will cause the image not to be found
• The slashes and backslashes of the relative path are wrongly written. The path is searched by slashes under Windows and the backslashes are used under Linux, so copy it, and check it carefully if the system is different.

  The above picture is not paying attention to the writing method of the relative path (the slash / and the backslash \ are used incorrectly), which leads to an error that the picture cannot be found.

  After editing, you can preview the interface according to the method provided by (2) preview wiki. In this way, our wiki website is built locally.

(5) Beautify the interface

  Some friends may think that this interface is not beautiful enough. Here mkdocs also provides a large number of template materials for you to choose from. You can check and choose by yourself. Here we recommend using the material theme to beautify.

material is a mkdocs theme, its advantages:

• Google's material design style.

• Progressive layout can be adapted to various devices for access.

• Supports a lot of plugins and extensions.

  The method of use is as follows:

  ①Installation

  pip install mkdocs-material
  

  ② Configuration: Open the configuration file mkdocs.yaml and add the following content

  theme:
    name: 'material'
  

  ③Personalized settings: If you want to modify the logo and color in the upper left corner of the webpage, you can add the following content

  theme:
      name: "material"
      logo:
          icon: "mkwiki"
      palette:
          primary: "black"
          accent: "white"
      language: "zh"
  

  Among them, the logo is to set the display in the upper left corner, which can be text, pictures, etc., the palette is to set the theme color, common colors can be selected, and the language is to set the language. Here, choose Chinese

5. Host the local wiki website to github

(1) Create a new warehouse:

Example: https://github.com/user_name/repository_name

  You can see that we have been prompted later what to do if we need to remotely push a warehouse to here

(2) Initialize the local warehouse

  Enter the project folder and initialize the local warehouse

cd my_wiki
git init 

  You can see that a .git folder will be created here, which cannot be seen in my_wiki. If you want to see it, you need to select the hidden folder

(3) Add local files to the local warehouse

git add .

  The . here means that all files have been added. Normally there is no output feedback here. As long as no error is reported, it is generally no problem and has been added successfully.

(4) Submit warehouse information

  Save local changes to the local repository

git commit -m"first version"

(5) Push to the remote warehouse

  Here we use the prompt information when we first created a new warehouse. If the readme file has been added and the prompt information is not displayed, it doesn’t matter. Just copy the address below and change it to your own warehouse address.

git remote add origin https://github.com/Chenying2000/my_wiki.git

git push -u origin main

  Note that it may also be the master. If an error is reported, you can try to modify it to master and run it again.

  Since github is maintained under the real-name system, if you are submitting warehouse maintenance for the first time, he will report an error and ask for your name and email address when submitting, just fill in the truth.

Error message:

*** Please tell me who you are.
Run  
git config --global user.email "[email protected]"  
git config --global user.name "Your Name" to set your account's default identity.
Omit --global to set the identity only in this repository. fatal:
unable to auto-detect email address (got 'Zero@zero.(none)')

Processing method:

git config --global user.email "gitHub邮箱"
git config --global user.name "gitHub用户名"

  Here I am not submitting for the first time, so I did not report an error. If you report an error, you can deal with it in the above way.

  Next push normally, it will ask your github account password. However, the account password method here has been abandoned in 2021. If you still enter the account password, it will report an error "support for password authentication was removed on August 13, 2021", allowing you to authenticate through the token method.

  At this time, replace the password with a personal token and paste it in, and you can successfully host it to github.

  Don’t worry if you don’t have a token, the token method for obtaining personal github will be added later.

(6) Supplement the token verification method of github

After entering, pull to the bottom

  Next, fill in the basic information and select the permission to grant the token as needed. It should be noted that if you want to remotely push the warehouse into it, at least the first option must be checked, otherwise there will be no permission later.

  The token will appear after setting, please be sure to copy and paste for backup! ! After this you will not be able to view it a second time.

  At this point, our personal token token is set up. Next, when pushing the warehouse, enter the user name as usual, but the password should be replaced by token.

(7) Render personal web pages

  At present, it is stored in the form of code in github, so how to deploy the website to github and access it through the URL? Next, a deployment tool of mkdocs will be used.

  Go back to the terminal, enter your own wiki project (my_wiki), and enter the command:

mkdocs gh-deploy

  It can be deployed with one click. Here you will be asked to enter the account password of github again. Just follow the above operation and replace the password with a personal token. A URL will be generated here. This URL is the access address of our webpage (the composition is github Personal account URL plus warehouse name)

  It may take a few minutes to wait here, and 404 not found will appear at the beginning. This is a normal phenomenon, because the deployment takes a certain time, just wait for a while and then visit it~The preview of the deployment result is shown in the figure below.