Miscellaneous tips, tricks, and thoughts from the author known as S0AndS0
The following are for those that wish to build documentation privatively or on another server.
Downloading Source
-
Make a directory path for GitHub sources and change directory
-
Clone the source and any submodules utilized by this repository
-
Change directory again and checkout a new branch for tracking changes
mkdir -vp ~/git/hub/S0AndS0
cd ~/git/hub/S0AndS0
git clone --recurse-submodules git@github.com:S0AndS0/S0AndS0.github.io.git
cd S0AndS0.github.io
git checkout -b fork
Note if building on a server, consider utilizing the Jekyll Administration project that is maintained for emulating many features of GitHub Pages privatively.
Forking
-
Change directory to repository
-
Add remote pointing to where you've forked this repository on GitHub
-
Fetch and set fork as default upstream that is pushed to and pulled from
cd ~/git/hub/S0AndS0/S0AndS0.github.io
## Replace <your-name> with your GitHub account name
git remote add fork git@github.com:<your-name>/S0AndS0.github.io
git fetch fork
git branch --set-upstream-to=fork/master
Building
-
Change directory to repository, and generate a coma separated list of configuration files
-
Update submodules and Jekyll related dependencies
-
Build source into files that many web-browsers understand
cd ~/git/hub/S0AndS0/S0AndS0.github.io
_config_files="_config.yml"
while read _p; do
_f="${_p##*/}"
[[ "${_f}" == '_config.yml' ]] && continue
[[ "${_f}" == '_config.yaml' ]] && continue
_config_files+=",${_f}"
done < <(ls -1 ./_config*.y*ml)
git submodule update --init --recursive --merge
# bundle install --path="${HOME}/.bundle/install"
bundle update
bundle exec jekyll build\
--config "${_config_files}"\
--destination "${HOME}/www"
For private builds GitHub Authentication setup is required to make full use of Metadata plugins. Those utilizing the Jekyll_Admin
repository may use the edit-configs
git shell command setting such configurations.
Note, if something is missing from the following please issue a Pull Request so that corrections may be reviewed.
-
Jekyll is what builds this repository into something that web servers may serve statically and many web-browsers are to render
-
GitHub Pages is what publicly hosts this repository, and may others.
Legal bits of Open Source software
Content and code (aside from third-party injections), of this file.
Copyright (C) 2019 S0AndS0
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation; version 3 of the License.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.