# jltechcn_docs

**Repository Path**: jltechcn/jltechcn_docs

## Basic Information

- **Project Name**: jltechcn_docs
- **Description**: 京伦全栈工程师知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2021-01-04
- **Last Updated**: 2021-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档使用手册


## 官网mkdocs安装与升级

推荐使用Pip安装(需要Python环境，详细参考:https://www.cnblogs.com/yuanzm/p/4089856.html)
#### 安装mkdocs-material
https://squidfunk.github.io/mkdocs-material/getting-started/

加速安装mkdocs-material组件和相关依赖插件（[MkDocs](https://www.mkdocs.org/), [Markdown](https://python-markdown.github.io/), [Pygments](https://pygments.org/) and [Python Markdown Extensions]）
```
pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs-material

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs-git-revision-date-localized-plugin  

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs-awesome-pages-plugin  
```
#### 更新mkdocs-material
https://squidfunk.github.io/mkdocs-material/upgrading/

Upgrade to the latest version with:

```
无加速更新
pip install --upgrade mkdocs-material
有加速更新
pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ --upgrade mkdocs-material
```
Inspect the currently installed version with:
```
pip show mkdocs-material
```
## 部署

### **Usage**

Add the following line to your mkdocs.yml:

```
theme:

name: 'material'
```

Mount the folder where your mkdocs.yml resides as a volume into /docs:



Start development server on http://localhost:8000



```
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```

Build documentation



```
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
```

Deploy documentation to GitHub Pages

```
docker run --name my-github-docs --restart always -dp 8210:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```

```
docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy 
```

For other installation methods, configuration options, and a demo, visit squidfunk.github.io/mkdocs-material

### with docker recommended

The official [Docker image][7] is a great way to get up and running in a few
minutes, as it comes with all dependencies pre-installed. Pull the image for the 
`latest` version with:

```
docker pull squidfunk/mkdocs-material
```

The `mkdocs` executable is provided as an entry point and `serve` is the default
command. Start the development server in your project root – the folder where
`mkdocs.yml` resides — with:

=== "Unix"

```
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material      
```
=== "Windows"
```
# docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material  
docker run --name jltech-mkdocs --restart always  -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material 
```

 官网容器镜像squidfunk/mkdocs-material没有安装插件，如果需要用到第三方插件，需要inspect容器中进行手动安装,再commit一个新容器

**How to add plugins to the Docker image?**

方法一：通过commit方式

 ```sh
docker run --name clean-mkdocs -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material

docker exec -it  clean-mkdocs /bin/sh   

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs-git-revision-date-localized-plugin  

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs-awesome-pages-plugin  

docker stop clean-mkdocs

docker commit -m "add plugin mkdocs-git-revision-date-localized-plugin and mkdocs-awesome-pages-plugin" -a "yichaoo" clean-mkdocs  yichaoo/mkdoc-material:v1.0

docker push yichaoo/mkdoc-material:v1.0
 ```

方法二:通过Dockerfile打包新的镜像

Material for MkDocs bundles useful and common plugins while trying not to blow up the size of the official image. If the plugin you want to use is not included, create a new `Dockerfile` and extend the official Docker image with your custom installation routine:

```sh
FROM squidfunk/mkdocs-material
RUN pip install ...
```

Next, you can build the image with the following command:

```sh
docker build -t squidfunk/mkdocs-material .
```

The new image can be used exactly like the official image.



### Organization and User Pages

User and Organization Pages sites are not tied to a specific project, and the
site files are deployed to the `master` branch in a dedicated repository named
with the GitHub account name. Therefore, you need working copies of two
repositories on our local system. For example, consider the following file
structure:

```
my-project/
    mkdocs.yml
    docs/
orgname.github.io/

```

After making and verifying updates to your project you need to change
directories to the `orgname.github.io` repository and call the
`mkdocs gh-deploy` command from there:

```
cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master
```
以本文档仓库为例
```
cd ../jltechcn/
mkdocs gh-deploy -f ../jltechcn_docs/mkdocs.yml -b master
```
Note that you need to explicitly point to the `mkdocs.yml` configuration file as
it is no longer in the current working directory. You also need to inform the
deploy script to commit to the `master` branch. You may override the default
with the [remote_branch] configuration setting, but if you forget to change
directories before running the deploy script, it will commit to the `master`
branch of your project, which you probably don't want.

Be aware that you will not be able to review the built site before it is pushed
to GitHub. Therefore, you may want to verify any changes you make to the docs
beforehand by using the `build` or `serve` commands and reviewing the built
files locally.

!!! warning

    You should never edit files in your pages repository by hand if you're using
    the `gh-deploy` command because you will lose your work the next time you
    run the command.