Adding docker-compose capability to host app locally (on localhost:8000)

1. Download docker compose sudo apt install docker-compose 2. Sanity Check docker compose --version 3. Enabling docker sudo systemctl start docker 4. Sanity Check with sudo systemctl status docker 5. Add user to the docker group sudo usermod -aG docker $USER 6. sudo apt remove python3-apt 7.

sudo apt update
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

8. sudo apt install docker-compose-plugin

9. docker compose up since it's Docker Compose V2

Quiz feature added!

Heavily inspired by mkdocs-jekyll please check them out I followed their PR to implement my quiz feature :D Thanks again!

PageCrypt was used as static github page encrptions

It was inspired by github-pages-jekyll-password-protection Further enhanced with password read in from GITHUB_SECRETS instead of _protected_pages.txt

Ruby (update from ruby 3.1.0p0 --> 3.3.1): Fixing Ruby compiler issue

I pretty much gave up on using RVM and used asdf instead (RVM = manages Ruby Version, asdf = manages more than Ruby, could be python ...) There are some conflicts with rvm & asdf, hence rvm was removed. Use rvm implode to remove all /rvm & gem uninstall rvm removing all rvm gems rubies

note: both rvm and asdf are dependencies managing tools

Fix dependabot issue:

bundle update <CVE vuln app version>
bundle install

git gogogo 'feat(fix): dependabot'

Reference from (https://gorails.com/setup/ubuntu/24.04)

1. Install all Ruby deps:
   

sudo apt-get update && sudo apt-get install git-core zlib1g-dev build-essential libssl-dev && libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev  && libcurl4-openssl-dev software-properties-common libffi-dev 

For MacOS using homebrew:

brew update && brew install git zlib openssl readline libyaml sqlite libxml2 libxslt curl libffi

2. Install Ruby version manager : ASDF
   

cd
git clone https://github.com/excid3/asdf.git ~/.asdf
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
echo 'legacy_version_file = yes' >> ~/.asdfrc
echo 'export EDITOR="code --wait"' >> ~/.bashrc
exec $SHELL # MacOS: source ~/.bashrc or source ~/.bashrc

3. Install ASDF plugin

asdf plugin add ruby
asdf plugin add nodejs

4. Install desired Ruby

asdf install ruby 3.3.1
asdf global ruby 3.3.1

5. Update latest Rubygems version

gem update --system

6. Check Ruby version and which Ruby dir

which ruby && ruby -v

7. cd back to the-docs dir and insatll/update all the bundle exes

bundle install

8. Update to Latest Gem & install bundler (= Ruby dep manager)

gem update --system && gem install bundler

9. Gem install the missing deps and bundle install again

gem install io-event -v 1.2.3
gem install ruby2_keywords -v 0.0.5
bundle install --force

10. cd back to the-docs and start up server:

bundle exec jekyll serve --livereload

Note: In case there are any errors/ warning messages when calling Gem You can try gem pristine <affected gem deps> --version <targeted-version> (i.e. gem pristine gem-wrappers --version 1.4.0)

Setting up deployment (Jekyll -> Github Page Site):

Refer to this Github document

High-level logic:

• Prereqs:
  • Jekyll (a Gem)
  • Bundler (a Gem and a Ruby dep orchestraor)
  • Ruby

1. Deploying Jekyll to GitHub Pages: Github repo -> Settings -> Pages -> Branch select main, /root

2. The default Github Action will run Based on this workflow file: Not 100% sure what this is

Default by github: pages build and deployment Manually create workflows please click here

Installation

Use the template

The Just the Docs Template provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "use the template"!

Note: To use the theme, you do not need to clone or fork the Just the Docs repo! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs.

You can easily set the site created by the template to be published on GitHub Pages – the template README file explains how to do that, along with other details.

If Jekyll is installed on your computer, you can also build and preview the created site locally. This lets you test changes before committing them, and avoids waiting for GitHub Pages.¹ And you will be able to deploy your local build to a different platform than GitHub Pages.

More specifically, the created site:

• uses a gem-based approach, i.e. uses a Gemfile and loads the just-the-docs gem
• uses the GitHub Pages / Actions workflow to build and publish the site on GitHub Pages

Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of just-the-docs and Jekyll it uses, as well as adding further plugins.

Use RubyGems

Alternatively, you can install the theme as a Ruby Gem, without creating a new site.

Add this line to your Jekyll site's Gemfile:

gem "just-the-docs"

And add this line to your Jekyll site's _config.yml:

theme: just-the-docs

And then execute:

$ bundle

Or install it yourself as:

$ gem install just-the-docs

Alternatively, you can run it inside Docker while developing your site

$ docker-compose up

Usage

View the documentation for usage information.

Contributing

Bug reports, proposals of new features, and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Submitting code changes:

• Submit an Issue that motivates the changes, using the appropriate template
• Discuss the proposed changes with other users and the maintainers
• Open a Pull Request
• Ensure all CI tests pass
• Provide instructions to check the effect of the changes
• Await code review

Design and development principles of this theme:

1. As few dependencies as possible
2. No build script needed
3. First class mobile experience
4. Make the content shine

Development

To set up your environment to develop this theme: fork this repo, the run bundle install from the root directory.

A modern devcontainer configuration for VSCode is included.

Your theme is set up just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When this theme is released, only the files in _layouts, _includes, and _sass tracked with Git will be included in the gem.

License

The theme is available as open source under the terms of the MIT License.

Footnotes

1. It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub. fortunately for me, the cicd rendering takes no more than 2 mins. ↩