Clean up page titles, render from frontmatter

[nchammas]

Clean up the site titles as follows:

• Render the page title as h1 if it's defined in the page's frontmatter.
• Remove duplicate titles now that the frontmatter titles are being rendered.
• Remove the singular page type, which is no longer needed.

I rendered and reviewed the built docs locally.

[nchammas]

Many page headings are set one level too deep. I can correct these in this PR as well, but wanted to start with a more contained set of changes first.

[nchammas]

I'll look into the build failure. One thing I'm wondering is: Why don't we have a GitHub Actions workflow generate the docs and push to asf-site on merge, and limit what we track and make PRs against to the clean source on master? Is that not possible for some reason?

[nchammas]

If any committers think it's a good idea, I would be happy to look into reworking the setup of this repo as follows:

• Create a master branch from the current asf-site branch but delete all generated output. master contains only the source.
• Delete all source from the asf-site branch. asf-site contains only the generated output.
• Make master the default branch and make asf-site a protected branch that only GitHub Actions can write to.
• Update the existing doc gen workflow to build the docs from master on every commit and update asf-site with the output.

I think this in theory gets us the ideal workflow:

• Contributions happen against master. Diffs are small and limited to what was changed directly by a contributor.
• Site is still served from asf-site as it is now.
• Contributors don't have to manually generate and commit rendered docs as part of PRs anymore.

[cloud-fan]

I think this is a good idea! BTW do we have to split into two branches? The GA job can generate html and commit to the same branch?

[nchammas]

We could leave it all on one branch like it is right now and just have Actions build the site for us. It doesn't solve the problem of diff noise, however. But if we want a more conservative approach, we could do that.

Better would be to split the source from the rendered output on two separate branches so that a PR like this has a proper diff illustrating my actual source changes, without the added noise of the rendered output diff.

Specifically, for this PR:

• My changes to the source: bd331d6, +27, -52
• The changes to the rendered output: 1b5753a, +1,633, -1,364

With one branch these diffs will always be mixed together. With two branches, we can keep them totally separate.

[cloud-fan]

automatically generating html files is already a big improvement, we can filter out html only commits manually if needed, I don't think that's a big advantage, as mostly people only look at PRs, not merged commits.

[nchammas]

I agree most of the time we are looking at PRs. But it is still a big advantage IMO when the local git status, remote git history, and repo structure all show only source changes. It just makes the whole repository look and work more like a "normal" one, and there is no need to ever think about filtering out noise.

I have been reading up on .asf.yaml and how we can test changes on a staging site (FYI: we already have one), automatically build the HTML, etc.

I have a plan to get us to a source-only master branch, but it will require close coordination with a committer. The result will be a much better setup and workflow for this repo.

On the other hand, I know this repo is not exactly the most exciting part of the project. So if you want to do something more conservative that is easier to review, I understand.

[cloud-fan]

I'd vote for single branch to avoid the new education cost for people contributing to this repo.

[nchammas]

Not sure why the Actions workflow now needs maintainer approval. Maybe it was already like this before but I didn't notice?

With all the Apache permissions restrictions -- necessary as they may be -- I think it will be hard for me to make any significant changes to our website workflow as a non-committer.