Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sdnbhd/251docs

251docs
https://github.com/sdnbhd/251docs

mkdocs

Last synced: about 1 month ago
JSON representation

251docs

Awesome Lists containing this project

README 

        
# 251docs by SDNBHD



[ℼ](#idxXXX)


## Table of Content (Toc)

* [Network Address Translation (NAT) Settings](#idx001)

  * [VirtualBox](#idx001)

  * [UTM](#idx001a)

* [GitHub Repo 251docs](#idx002)

* [Debian Packages](#idx003)

* [CLONE Your GitHub Repo on VirtualBox](#idx004)

* [File .gitignore](#idx005)

* [Check Python, Pip, and Venv](#idx006)

* [Python Virtual Environment](#idx007)

* [Activate the Virtual Environment](#idx008)

* [MkDocs and Plugins](#idx009)

* [MkDocs inside folder "docs/"](#idx010)

* [Test from VirtualBox](#idx011)

* [Build the MkDocs site](#idx012)

* [Switch to gh-pages branch and back to master](#idx013)



[ℼ](#)


## Network Address Translation (NAT) Settings



### VirtualBox



MkDocs is using local port 8000. 

On your VirtualBox, you must redirect/translate the local port 8000 to the host port 4999.

I am already using 5000 for Jekyll and 5001 for Docusaurus.



* VirtualBox Settings

  * Network:Adapter1:

    * Enable Network Adapter

    * Attached to: NAT

    * Port Forwarding:

      * 127.0.0.1:4999 (Host) --- 10.0.2.15:8000 (Guest)








[ℼ](#)



### UTM



MkDocs is using local port 8000. 

On your UTM, you must redirect/translate the local port 8000 to the host port 4999.

I am already using 5000 for Jekyll and 5001 for Docusaurus.



* UTM Settings

  * Network Mode: Emulated VLAN

    * Port Forward: New

      * Protocol: TCP

      * Guest Address: 10.0.2.15

      * Guest Port: 8000

      * Host Address: 127.0.0.1

      * Host Port: 4999

   * SAVE








[ℼ](#)


## GitHub Repo 251docs



* Create a new [GitHub](https://github.com/) repo.

  * New Repository

  * Repository Name: "251docs"

  * Description: "251docs"

  * Public

  * Add README.md

  * Add .gitignore: Python (temporary)

  * Choose any free LICENSE

  * See also 

* Create a GitHub page.

  * (Create branch: gh-pages), apparently will automatically create a GitHub Page?!

  * See also 



[ℼ](#)


## Debian Packages



Make sure the following Debian packages are present in your system.



```

# USER privilege.

export DEBS="

aptitude

build-essential

git

libffi-dev

libssl-dev

python3

python3-dev

python3-pip

python3-venv

sudo

vim

"

time sudo apt-get install $DEBS -y

date



```



[ℼ](#)


## CLONE Your GitHub Repo on VirtualBox

* E.g. repo "251docs/"



```

GITHUB="sdnbhd"

REPO="251docs"

git clone [email protected]:$GITHUB/$REPO.git

cd $REPO/



```

* REMEMBER: You are not **CBKADAL**!

* Write your memo on file "README.md".

  * Update/push "README.md" regularly.



[ℼ](#)


### File .gitignore



If you still not, go to (cd) repo "251docs/".

Copy the following into your .gitignore file:

https://raw.githubusercontent.com/cbkadal/251docs/master/.gitignore



[ℼ](#)


## Check Python, Pip, and Venv



```

python --version

pip --version

python -m venv --help



```



[ℼ](#)


## Python Virtual Environment



```

# A centralized ".virtualenvs/" directory

mkdir -pv ~/.virtualenvs/



# Create a Virtual Environment

python3 -m venv ~/.virtualenvs/$(basename $(pwd))



```



[ℼ](#)


## Activate the Virtual Environment

* Before working with "MkDocs", always activate the virtual environment!



```

source ~/.virtualenvs/$(basename $(pwd))/bin/activate



```



* And upgrading PIP inside the Virtual Environment



```

# Upgrade

pip install --upgrade pip

# Check the version

pip --version



```



[ℼ](#)


## Install MkDocs and additional MkDocs plugins



```

pip install mkdocs mkdocs-material



```



* Upgrade, Clean Up, and Verify Version



```

pip install --upgrade pip mkdocs mkdocs-material

pip cache purge

mkdocs --version



```



[ℼ](#)


## MkDocs inside folder "docs/"



```

mkdir -pv docs/

cd docs/

mkdocs new .



```



[ℼ](#)


## Test from VirtualBox



```

mkdocs serve --dev-addr=0.0.0.0:8000



```



* Check it out at "localhost:4999" (HOST)



[ℼ](#)


## Build the MkDocs site

* Build, commit, and push (master)



```

mkdocs build

git add .

git commit -m "Save uncommitted changes"

git push



```



[ℼ](#)


## Switch to gh-pages branch and back to master



```

git show-ref  --quiet         refs/heads/gh-pages && git      branch -D       gh-pages

git ls-remote --exit-code --heads origin gh-pages && git push origin --delete gh-pages

git checkout    --orphan gh-pages



git rm -rf .

cp -rv site/* ../

cd ../

git rm -rf docs/ README.md .shsh

git add .

git commit -m "Deploy MkDocs site"

git push origin gh-pages

git checkout master



```



* Checkit out at , but your are not CBKADAL!






```

REVISI: Fri 29 Nov 2024 15:00

REVISI: Fri 29 Nov 2024 14:04

REVISI: Fri 29 Nov 2024 14:02

REVISI: Fri 29 Nov 2024 14:01

REVISI: Fri 29 Nov 2024 14:00

STARTX: Tue 26 Nov 2024 12:00

```