An empty project example with sane defaults for CI in GitHub Actions and CD to GitHub Pages

[almereyda]

For clean separation of concerns, it could be nice to decouple the content from the site generation code, in so we could just put .ter/ and docs/ subdirectories into a repository, and have that handled by the ter CLI.

In a further step, one could also consider to decouple the presentation layer ("theme") from the site generator.

How could these separations achieved, and which good examples are known from Deno land, where this works well?

[kkga]

For clean separation of concerns, it could be nice to decouple the content from the site generation code, in so we could just put .ter/ and docs/ subdirectories into a repository, and have that handled by the ter CLI.

I'm not sure what exactly you mean in this case. You can put content in any folder and run ter with the --input option:

deno run -A --unstable https://deno.land/x/ter/main.ts --input docs

decouple the content from the site generation code

Which code are you referring to? You don't need to have any code in your repository since you're running ter via the URL.

[almereyda]

I think I need to understand a bit better how things work in Deno land.

What I would like to see is an example repository, say a starter template, with build workflow and a good README that only consists of the content, but has its site deployed to one of: Deno Deploy, Vercel, S3, another branch, GitHub pages

Then people can easily instantiate their ter website.

• Creating a template repository - GitHub Docs

[kkga]

What I would like to see is an example repository, say a starter template, with build workflow and a good README that only consists of the content, but has its site deployed to one of: Deno Deploy, Vercel, S3, another branch, GitHub pages

I'm not sure how much value a template repo will provide, since the only extra file that users need is the configuration, unlike something like Lume which uses local template files.

As for deploying, this is specific to user's setup and only Deno Deploy uses a GitHub workflow to build the site. Vercel builds and deploys on their servers by running the command you specify in project settings.

[almereyda]

Okay, cool.

Just for having an example on how to build a ter page without directly reusing this repository here, I should refactor my "instance" to the model that you suggest, and provide a PR here for the docs/ to document this.

On Sun, 2 Jul 2023 at 13:35, Gadzhi Kharkharov @.***> wrote:

What I would like to see is an example repository, say a starter template, with build workflow and a good README that only consists of the content, but has its site deployed to one of: Deno Deploy, Vercel, S3, another branch, GitHub pages

I'm not sure how much value a template repo will provide, since the only extra file that users need is the configuration https://ter.kkga.me/usage/configuration, unlike something like Lume https://github.com/lumeland/base-blog which uses local template files.

As for deploying, this is specific to user's setup and only Deno Deploy uses a GitHub workflow to build the site. Vercel builds and deploys on their servers by running the command you specify in project settings.

— Reply to this email directly, view it on GitHub https://github.com/kkga/ter/issues/44#issuecomment-1616612378, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAMRV7AVQDIOTIR5YDGCBQTXOFMIJANCNFSM6AAAAAAZZ4KC74 . You are receiving this because you authored the thread.Message ID: @.***>

[kkga]

example on how to build a ter page without directly reusing this repository here

what do you think is missing on the usage page?

[almereyda]

It appears I hadn't passed by there, despite it is the one page with a star, when seen listed from another page.

From how it is formulated, I would like to see a complete example for an exemplary life cycle of a site, e.g. under a headline like:

• Build a site automatically

Just so that no one else get's the idea to fork your ter repository like I did, just because it is the only documented example of a page automatically built with it.

Maybe mentioning some working Deno deployment environments, like this Vercel, GitHub Actions + Deno Deploy, GitHub Actions + GitHub Pages,, GitLab CI + GitLab Pages and other common ones can help to spark ideas on how to implement it in a specific use case.

On Sun, 2 Jul 2023 at 14:40, Gadzhi Kharkharov @.***> wrote:

example on how to build a ter page without directly reusing this repository here

what do you think is missing on the usage page?

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[kkga]

I added some quick start notes in the GitHub readme: https://github.com/kkga/ter#quick-start. Hopefully this will help.

[almereyda]

Thank you!

I will follow up here, when I have more to report.

On Sun, 2 Jul 2023 at 20:23, Gadzhi Kharkharov @.***> wrote:

I added some quick start notes in the GitHub readme: https://github.com/kkga/ter#quick-start. Hopefully this will help.

— Reply to this email directly, view it on GitHub https://github.com/kkga/ter/issues/44#issuecomment-1616761825, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAMRV7FJYWM4ZVHXOIDTJ7LXOG4B7ANCNFSM6AAAAAAZZ4KC74 . You are receiving this because you authored the thread.Message ID: @.***>

[almereyda]

Decoupling content and code and deploying to the new GitHub Pages with Actions (and without CNAME files nowadays) has been shown in ecobytes/the.compost.place. The pieces came nicely together with copy and pasting, and I only had to change _dist to _site once in the deno run step, instead of twice in the fix permissions and upload-pages-artifact steps. See for yourself:

https://github.com/ecobytes/the.compost.place/blob/248f1f45545d03adbd2cb5a41359587008cdb9ef/.github/workflows/build-deploy.yml

Feel free to put this in the instructions. It doesn't have a license yet, why I say that here. You should use _dist, obviously.

---

For reference, this took 20' setting up, and 10' cleaning up and documenting here. Should be way faster with a copy and paste template. It will be even faster with a GitHub repository template that has the the config, the contents and the workflow already in place, and I'm going to investigate how that would work at some point.

[kkga]

I'm confused. What exactly are separating?

[almereyda]

Sorry for the confusion. It appears I have been trying to put the cart before the horse.

The original post was not clear on its intention, and did not express the need clearly. I have now renamed the post. Please allow me to recapitulate the steps in my earlier reasoning:

• I needed an example for a default project on how to run ter on one of its content repositories.
• I had only found kkga/ter (ter.kkga.me, and also ter.deno.dev?) and forked that into my namespace, working from there.
• I was distracted by all the application code in my source tree, for that I only wanted a clean website repository.
• It seems I completely disregarded the existing deploy instructions, and were unable to abstract to my use case without a example.
• I had now built such an example that I had in mind, using GitHub Actions to deploy to GitHub Pages. This snippet I wanted to share and offer for inclusion.

That is, before I now checked again and learned to knww kkga/kkga (kkga.me. But that repository doesn't have a GitHub workflow, but brings the suggestion to include Deno tasks with the site. In comparison, keeping pages in a subdirectory leaves us the option to include a readme to a ter project.

What I was trying to ask, is:

• Would you like to include the GitHub Pages example into the ter documentation?

It is only now that I realise that the documentation is also built from this repository, and I can just do that with a PR against https://github.com/kkga/ter/blob/master/docs/usage/deploy.md

That including a sentence like the following before the last line in the README may also be good:

Documentation

The documentation is built from the docs/ folder

The confusing about _dist or _site came from both being used in the documentation and code:

https://github.com/kkga/ter/blob/cfd17c9b7310abc4094cd9cbd5d7c96fcd65d356/docs/usage/index.md?plain=1#L26

From looking again at the sources, it is obvious that _site is the default.

I would include that in the to be offered PR as well.

With all that included, in the state it is now, I would consider ecobytes/the.compost.place to be in a state where it could serve as a nice ter template repository, with the readme.md explaining how to use it, and some more generic content put into config.json and index.md.

Would you agree?