Website setup

[aepfli]

The current website setup needs to be more straightforward and has many unknowns for new users.

• How is it built?
• Why do I need this tmp folder?
• Where is the rest of the page stored?

Overall the initial setup is fine, but it adds a lot of boilerplate for building it, and pull request verification is also challenging.

Goal

We want to make the Developer Experience for the documentation smoother. Ideally, we separate the content from the layout. And reduce the obvious boilerplate for developers.

Proposal

As Hugo is powerful, we can leverage a lot of Hugo functionality to achieve a leaner structure.

1. we make the documentation build within this repository with Hugo features, instead of a git clone we will include the layout with Hugomodules.

   module:
     hugoVersion:
       extended: true
     imports:
     - path: github.com/aepfli/lifecycle-toolkit-docs #current fork we need to adapt the go.mod file to have the correct name :)
       mounts:
       - source: static
         target: static
       - source: layouts
         target: layouts
       - source: data
         target: data
       - source: assets
         target: assets
       - source: archetypes
         target: archetypes

   • adapt go.mod file in layout repo docs: website build improvements #806
   • remove git clone from make file docs: website build improvements #806
   • add config.yaml to doc directory and a proper go.mod file (https://gohugo.io/getting-started/configuration/#merge-configuration-from-themes important for proper merging) docs: website build improvements #806

2. use the outcome of the first one to generate an integrated build pipeline within the this repository

   • neflify build with preview docs: add Netlify configuration and advanced build #892
   • pull request link verification with markdown-link-check and htmltest docs: add htmltest verification for documentation #932
   • ensure that we do have a robot.txt which ensures that this page is not getting indexed
   • link the dev version to this netlify build. Due to that, we don't need to copy it docs: add Netlify configuration and advanced build #892

3. improve the main site build

   • separate content and layout (two distinct repositories) (this way we can use the layout even for other pages)
   • link the dev version in the dropdown to the main branch build of this repository docs: add Netlify configuration and advanced build #892 chore: fix development url in page branch #925
   • ensure that the docs upload is working as it is without the dev part

what do we solve with this?

The build is self-contained even in this repository.
We can easily verify that our current version is in a proper status without invoking another repository or build.
Our adaptions within this repository are still relatively low (3 additional files (go.mod, go.sum, config.yaml) and reduce makefile logic.
Additionally, we reduce the need to copy/paste the main branch.

Discuss

• do we want to separate the layout and content?
• does this approach sound desirable?

related prs:

• docs: improve netlify build #920
• docs: website build improvements #806
• docs: add htmltest verification for documentation #932
• docs: add Netlify configuration and advanced build #892
• chore: fix development url in page branch #925
• docs: change Development url #923

[mowies]

Sounds like a good approach, I like it!

[thisthat]

I also like the approach since it:

• allows custom local build
• reduce copy/paste
• simplify pipelines
• keeps the docs next to the code

Great suggestion @aepfli 🚀

[aepfli]

this is something, which might now be a little bit controversial, but I'll put it here anyways :) it is just a brain dump :)

Do we need our dedicated documentation repository for the content? eg. Jekyll and github_pages have their pages branch where they keep the content.

Pros:

• it would reduce the complexity of pushing to another repository
• we would have one netlify build for everything. We would need to set the default netlify branch to the page branch.
• all changes to already done documentation will take place within the same repository - which generates IMHO a better overview

Cons:

• one additional long-living branch
• still not 100% clear regarding build/etc

[mowies]

I think i discussed that with someone already 🤔
I don't like that approach cus then you have a suuuuuper divergent long living branch in the same repo with the code. I'd rather have that separated. That's my only problem with it.
Other than that, it would make things a little easier if we had everything in the main repo, but then we have a versioning issue again potentially, with all the code for all version always sitting there.

[aepfli]

We two talked about this. I would only put the webpage into this branch - no other source code, just the page. In our initial discussion, we discussed a long-living branch per minor version, which would be a lot to maintain. This way, the documentation is the only content in there. and instead of copying it to another repository, we would write it to the same repo in another branch.

This was a fancy idea of reducing the number of repositories and keeping the source of truth within one.

[aepfli]

Theory crafting

We do have our dev docs within the main branch, and we do have a pages branch as our serving branch for all versions of documentation.

release workflow

As soon as a new release is created, the docs folder of this release is moved to the pages branch and gets suffixed with the version.
Additionally the version dropdown gets enhanced with the new version.

If the release is tagged as latest release:

1. we will move the existing docs folder to do docs-{version}. The version is determined by a version file within the docs folder, or as part of the frontmatter of the _index.md within this docs folder

2. we will use the existing docs folder of the main branch, copy it to the pages branch. adapt the frontmatter and create a version file containting the version

change the version menu generator to look for all docs folders and add them based on their version file, but .

• just the last 5 versions?
• or the last supported versions?

Following snippet would be a version menu created based on folders, rather than configuration

• docs/layouts/partials/navbar-version-selector.html

<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
	{{ .Site.Params.version_menu }}
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
	{{ range sort .Site.Pages ".File.ContentBaseName" "desc" -}}
      {{ if (findRE "docs" .File.ContentBaseName) -}}
      {{ $version := replaceRE "docs-" "" .File.ContentBaseName -}}
      <a class="dropdown-item" href="{{ .RelPermalink }}">{{ $version }}</a>
      {{ end -}}
      {{ end -}}
</div>

[aepfli]

3 unrefined versions of building a verison menu:

• first file base
• API based
• traditional config base

	{{ range first 5 (sort .Site.Pages ".File.ContentBaseName" "desc") -}}
      {{ if (findRE "docs" .File.ContentBaseName) -}}
      {{ $version := replaceRE "docs-" "" .File.ContentBaseName -}}
      <a class="dropdown-item" href="{{ .RelPermalink }}">folder-{{ $version }}</a>
      {{ end -}}
    {{ end -}}

    {{ range first 5 (getJSON "https://api.github.com/repos/keptn/lifecycle-toolkit/releases") -}}
      {{ $p := . -}}
      <a class="dropdown-item" href="docs-{{ $p.tag_name }}">{{ $p.tag_name }}</a>
    {{ end -}}
    
    {{ $path := "" }}
    {{ if .Site.Params.version_menu_pagelinks }}
        {{ $path = .Page.RelPermalink }}
    {{ end }}
    {{ range .Site.Params.versions }}
      <a class="dropdown-item" href="{{ .url }}{{ $path }}">{{ .version }}</a>
    {{ end }}

[aepfli]

only thing missing before closing this issue is the migration to the live url