Repo Instruction

Project Structure

├── README.md : project instructions and guide
├── .vscode : vscode configuration files, automatically generated by vscode
├── upload.sh : upload the file to your online repository, e.g. github. Modify the file to your own repo.
├── win-upload.bat : upload the file to your online repository, e.g. github. Modify the file to your own repo.
├── preview.bat : preview the website locally. This is for Windows.
├── preview.sh : preview the website locally. This is for MacOS and Linux.
├── Ops.sh : clean the existing folder, pull repo, build the website to generate the entrance html file. Then the http server will serve the website.
├── mkdocs.yml : mkdocs configuration file
├── mkdocs-env : this folder is automatically generated by mkdocs
├── requirements.txt : python packages required by mkdocs, to install: pip install -r requirements.txt
├── .editorconfig : editor configuration file
├── .gitignore : git ignore file. note that, better build the website in the server rather than locally
├── material : theme materials
├── site : built website to be deployed. To avoid some issues, I remove this folder on the web server and build this folder again on the web server.
└── docs : documentation files, this is the root directory of the website
    │── static: static files, not all here. Most are in respective folders. 
    │   │── images: images
    │   └── videos: videos
    │── blog: blog posts
    │   │── index.md: blog index page
    │   └── posts: blog posts
    │── ReferenceCode: reference code for copy and paste
    │── javascript: javascript files for extensions
    │── index.md: home page - in English
    │── index.zh.md: home page - in Chinese
    └── Other pages and resources

How To Get Started On Local Machine

• Step 1: Find a folder that you want to store the project, and clone the repo to your local machine. To do so, open your terminal and type the following command:

git clone https://github.com/Shuaiwen-Cui/Infinity.git

• Step 2: Change directory to the root directory of the website

cd Infinity

• Step 3: Install MkDocs and Material Theme

pip install mkdocs
pip install mkdocs-material

• Step 4: Install the required python packages

pip install -r requirements.txt

note: if other modules are required, please google for solutions.

known issues: for package - rss, minify, i18n. You can use the follow command to install them

pip install mkdocs-minify-plugin
pip install mkdocs-rss-plugin
pip install mkdocs-static-i18n

• Step 5: Build the website

mkdocs build

• Step 6: Run the website

mkdocs serve

• Step 7: Open the website in your browser

http://127.0.0.1:8000

How To Deploy The Website To The Server

For deployment, you need to modify the deployment-related files first, namely, upload.sh, win-upload.bat, and Ops.sh. upload.sh and win-upload.bat are for uploading, where upload.sh can be used for all platforms, and win-upload.bat can only be used for Windows. Ops.sh is for server side operations, where you can use it to install packages, etc. Open these files, replace the repo link with your own repo link.

• For uploading

If you use MacOS or Linux, you can use the following command to upload the website to the server

bash upload.sh

If you use Windows, you can use the following command to upload the website to the server. This may require you to install git bash.

./upload.sh

if it does not work, you can use win-upload.bat

./win-upload.bat

• For server side operations

First, if this is the first time for deployment, you need to clone the repo to the server, use the following command

git clone https://github.com/Shuaiwen-Cui/Infinity.git

change directory to the root directory of the website

cd <root directory of the website>

If the server is Linux, you can use the following command to do a series of operations on the server

bash Ops.sh

If the server is Windows, you can use the following command to do a series of operations on the server

./Ops.sh

for more details, please refer to the page http://www.cuishuaiwen.com:8000/PROJECT/TECH-BLOG/mkdocs_and_material/