|
1 | 1 | # geonode.org |
2 | 2 |
|
3 | | -Prerequisites |
4 | | -------------- |
5 | | - sudo apt-get install ruby-full build-essential zlib1g-dev |
6 | | - echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc |
7 | | - echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc |
8 | | - echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc |
9 | | - source ~/.bashrc |
10 | | - gem install bundler |
11 | | - bundle install |
12 | | - |
13 | | -Workflow |
14 | | --------- |
15 | | - |
16 | | - # edit content |
17 | | - bundle exec jekyll serve # default port is 4000, set explicitly with -P |
18 | | - # view at http://localhost:4000 |
19 | | - # adding blogposts |
20 | | - cd _drafts |
21 | | - vi newpost.md |
22 | | - # make sure to set the following YAML front matter: |
23 | | - # layout: base |
24 | | - # |
25 | | - # preview with `jekyll build --drafts` or `jekyll serve --drafts` and draft will show up as latest post |
26 | | - # when you are ready to publish: |
27 | | - # - rename the file as per the current YYYY-MM-DD |
28 | | - git mv _drafts/newpost.md _posts/YYYY-MM-DD-newpost.md |
29 | | - vi _posts/YYYY-MM-DD-newpost.md |
30 | | - # commit and push |
31 | | - bundle exec jekyll build |
32 | | - git commit -m 'publish article' |
33 | | - git push origin master |
| 3 | +Source for the [GeoNode](https://geonode.org) project website, a static site built with [Jekyll](https://jekyllrb.com/) and served at [geonode.org](https://geonode.org). |
| 4 | + |
| 5 | +## How it's published |
| 6 | + |
| 7 | +The site is built and deployed automatically by GitHub Actions (`.github/workflows/jekyll.yml`): every push to the `master` branch runs `jekyll build` and deploys the result to GitHub Pages. There is no manual publish step — merging to `master` is what ships the site. |
| 8 | + |
| 9 | +The build uses the gems pinned in this repo's `Gemfile`. The site tracks the [`github-pages`](https://github.com/github/pages-gem) gem, which keeps Jekyll and its plugins aligned with what GitHub Pages supports (currently Jekyll 3.x). |
| 10 | + |
| 11 | +## Local development |
| 12 | + |
| 13 | +You can run the site either with Docker (no Ruby toolchain needed on your machine) or with a native Ruby setup. |
| 14 | + |
| 15 | +### Option A — Docker (recommended) |
| 16 | + |
| 17 | +Build the image once: |
| 18 | + |
| 19 | +```bash |
| 20 | +docker build -t geonode-site . |
| 21 | +``` |
| 22 | + |
| 23 | +Serve the site at <http://localhost:4000>: |
| 24 | + |
| 25 | +```bash |
| 26 | +docker run --rm -p 4000:4000 geonode-site |
| 27 | +``` |
| 28 | + |
| 29 | +Serve with live-reload while editing, by mounting the working tree: |
| 30 | + |
| 31 | +```bash |
| 32 | +docker run --rm -p 4000:4000 -v "$PWD":/site geonode-site |
| 33 | +``` |
| 34 | + |
| 35 | +Build only and extract the generated static site to `./_site` (no server): |
| 36 | + |
| 37 | +```bash |
| 38 | +docker run --rm -v "$PWD":/site geonode-site bundle exec jekyll build |
| 39 | +``` |
| 40 | + |
| 41 | +> On Linux/WSL the generated files are owned by `root`. To have them owned by |
| 42 | +> your user, add `--user "$(id -u):$(id -g)"` to the `docker run` command. |
| 43 | +
|
| 44 | +### Option B — Native Ruby |
| 45 | + |
| 46 | +Install the prerequisites (Debian/Ubuntu example): |
| 47 | + |
| 48 | +```bash |
| 49 | +sudo apt-get install ruby-full build-essential zlib1g-dev |
| 50 | +``` |
| 51 | + |
| 52 | +If gems fail to install globally, install them under your home directory: |
| 53 | + |
| 54 | +```bash |
| 55 | +echo '# Install Ruby gems to ~/gems' >> ~/.bashrc |
| 56 | +echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc |
| 57 | +echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc |
| 58 | +source ~/.bashrc |
| 59 | +``` |
| 60 | + |
| 61 | +Install the project gems and serve the site: |
| 62 | + |
| 63 | +```bash |
| 64 | +gem install bundler |
| 65 | +bundle install |
| 66 | +bundle exec jekyll serve # default port 4000; override with -P <port> |
| 67 | +``` |
| 68 | + |
| 69 | +View at <http://localhost:4000>. |
| 70 | + |
| 71 | +## Writing a blog post |
| 72 | + |
| 73 | +Drafts live in `_drafts/` and are excluded from production builds. |
| 74 | + |
| 75 | +1. Create the draft and set its YAML front matter: |
| 76 | + |
| 77 | + ```bash |
| 78 | + cd _drafts |
| 79 | + vi newpost.md |
| 80 | + ``` |
| 81 | + |
| 82 | + ```yaml |
| 83 | + --- |
| 84 | + layout: base |
| 85 | + --- |
| 86 | + ``` |
| 87 | + |
| 88 | +2. Preview drafts (they show up as the latest post): |
| 89 | + |
| 90 | + ```bash |
| 91 | + bundle exec jekyll serve --drafts |
| 92 | + # or, with Docker: |
| 93 | + docker run --rm -p 4000:4000 -v "$PWD":/site geonode-site \ |
| 94 | + bundle exec jekyll serve --host 0.0.0.0 --drafts |
| 95 | + ``` |
| 96 | + |
| 97 | +3. When ready to publish, move the draft into `_posts/` with a dated filename: |
| 98 | + |
| 99 | + ```bash |
| 100 | + git mv _drafts/newpost.md _posts/YYYY-MM-DD-newpost.md |
| 101 | + vi _posts/YYYY-MM-DD-newpost.md |
| 102 | + ``` |
| 103 | + |
| 104 | +4. Commit and push to `master` — the GitHub Actions workflow builds and |
| 105 | + deploys the site automatically: |
| 106 | + |
| 107 | + ```bash |
| 108 | + git commit -am 'publish article' |
| 109 | + git push origin master |
| 110 | + ``` |
0 commit comments