Setup .gitpod.yml for super simple web based editing and live preview.

[bwklein]

It might be nice in this repo to provide a starting .gitpod.yml file that will run the example site in GitPod.io. This would let people clone the site and then jump directly into editing and live preview of their new site without Docker, local installs of anything, etc.

Here is an example that works great with a Hugo+Docsy site I have setup.

image: klakegg/hugo:0.88.0-ext-ubuntu-ci
ports:
  - port: 1313
    onOpen: open-browser
tasks:
  - name: Setup environment and run Hugo server.
    init: |
      git submodule update --init --recursive
      npm install
    command: hugo server --buildDrafts --buildFuture --baseUrl $(gp url 1313) --liveReloadPort=443 --appendPort=false

Because I am using the klakegg/hugo image, I don't need to set --bind=0.0.0.0 as a parameter for the command. Otherwise, the --bind parameter is necessary to get Hugo's Live Reload feature to work correctly.

[LisaFC]

@emckean!

[bwklein]

@LisaFC and @emckean I recently added this to the Hugo site for The Good Docs Project too. Works like a charm. :D

[emckean]

So I tried out GitPod and it's really very cool -- but I feel weird adding another .yml file to the repo for a separate service that isn't in our main deploy path. What about adding it to the docs as an option, especially since you don't even need a .yml file -- connecting GitPod to your repo gives you the option to just copy/paste it into the prebuild UI.

[bwklein]

@emckean That's interesting, I didn't see the copy/paste option for that. I am also not sure how you update the version of Hugo specified or any of those other settings once you have done that, outside of modifying the .yml file in the repo. Sounds like adding it to the docs and how to use it when you connect would be an excellent option.

[mikenikles]

connecting GitPod to your repo gives you the option to just copy/paste it into the prebuild UI

Only people who have write permissions for a given repo can do that. If you don't want the .gitpod.yml in the repo root (which is completely understandable), you could follow the onboarding at https://gitpod.io/new and configure the repo in the browser as you already experienced. Once done, no additional config is required in the repo itself.

Another idea is a solution less known: https://github.com/gitpod-io/definitely-gp to store .gitpod.yml files for repos you don't have write permissions or, like in this case here, where adding the configuration file to the repo is not ideal.

[bwklein]

Yeah, my experience is that the gitpod.yml in the repo is valuable because it does define the build tools, docker file, etc. that are used in the development environment for editors/developers to use with the web IDE. If you don't have write permissions, Gitpod will automatically fork the repo and help set up a Merge/Pull Request from the personal fork back into the source repo. Making contributions back to the project super simple.

I get the sensitivity to not including something that is not in the primary build tools, but I think that provides someone with an almost one-click option to greatly improve the developer experience which in my opinion is more important than the build tooling setup.

This file will allow someone to click the button to use this template and then immediately jump into the web IDE and start working on their new site with live editing/preview. Without a moment spent installing anything on their machine, setting up the proper git permissions for the project locally, etc. It makes it too easy to use, and that's an important thing I look for in a template to help me get started.

Having said all that, I'll defer to your choice. I will say that this file will definitely be in The Good Docs 'easy-button' project. 😊

[emckean]

Those are some good points ... 🤔 I'll bring this up w/some of the other folks and see what they think!