Skip to content

Latest commit

 

History

History
120 lines (89 loc) · 5.63 KB

README.md

File metadata and controls

120 lines (89 loc) · 5.63 KB
Raw

https://ircama.github.io/osm-carto-tutorials/

OpenStreetMap Carto Tutorials - DOC-JEKYLL theme

Unofficial tutorials for openstreetmap-carto.

  ┌┬┐┌─┐┌─┐   ┬┌─┐┬┌─┬ ┬┬  ┬
   │││ ││  ── │├┤ ├┴┐└┬┘│  │
  ─┴┘└─┘└─┘  └┘└─┘┴ ┴ ┴ ┴─┘┴─┘

This Jekyll-based theme named DOC-JEKYLL is specifically intended for static technical documentation deployable on GitHub Pages.

Information on the usage of this theme can be found in how to contribute.

Credits:

Licensed under the MIT License

Hosted by GitHub

This site can be cloned and reused freely. The following files and data are specific and need deletion or customization when forking this site for different purposes:

  • _config.yml, including all project specific parameters (shall be customized)
  • README.MD (shall be customized)
  • public/favicon.ico and public/apple-touch-icon-precomposed.png (shall be customized)
  • All files in "pages", "_notes" and "_posts" directory (shall be removed)
  • googlec45135b10de87878.html (shall be removed)
  • the pages subdirectory inside _includes

Summary of the main changes from the default Lanyon Theme:

  • additional settings in _config.yml
  • developed improved sidebar
  • added last modification date for the whole site and for each page (using GitHub commit dates)
  • added last site version (using last GitHub tag name)
  • revised css and js to allow fully responsive site for smartphones, tablets and different desktop resolutions
  • developed extensive style for print including automatic chapter numbering
  • developed a smart site map
  • improved Atom RSS
  • added integration with Disqus, Google Search Custom, Google Analytics
  • Home page revised
  • improved lanyon.css and poole.css
  • Developed an extension of the Lanyon stylesheet which supports drawings.
  • Usage of compressed scss styles. Single style.css style compiled and compressed afer merging all scss/css styles
  • Integrated a Liquid HTML compressor
  • Added a very basic Liquid Javascript compressor
  • Added footnotes management

How to locally deploy and test this website

This chapter summarizes all the steps to locally deploy and test this jekill-based GitHub Pages website with Ubuntu.

  • Clone this repository (e.g. with GitHub Desktop)

  • Not strictly necessary: install Snap:

    sudo apt update
sudo apt install snapd

  • Install Jekyll and related prerequisites:

    cd

# Test that prerequisites are already installed (each command shows how to install the related prerequisite if missing)
ruby -v # if missing, install it with e.g.: snap install ruby --classic
gem -v
cc -v
g++ -v
make -v

# Install Ruby
sudo apt-get install ruby-full build-essential zlib1g-dev
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Install jekyll and bundler
gem install jekyll bundler

  • Update the bundler version in Gemfile.lock. (Gemfile.lock is removed, so that Bundler will fetch all remote sources, resolve dependencies and install all needed gems. In general, this also fixes Dependabot security updates on vulnerabilities.)

    cd ~/Documents/GitHub/osm-carto-tutorials
rm Gemfile.lock
bundle install

# Alternatively, you can run "bundle update --bundler"

  • Finally, serve the website

    bundle exec jekyll serve