Host documentation on the website, rather than linking to GH repo

[chalin]

Visit https://containerd.io/docs/getting-started/, and you'll see this:

Visit https://containerd.io/docs/, and the reader is redirected to https://github.com/containerd/containerd/tree/main/docs.

So essentially, there are no docs on the website. I understand how this came to be: delays in syncing docs from the code repo to the website repo, but docs should be hosted directly on the website, regardless of how they get there.

There are two main recommended ways to handle this situation (preferred way first):

1. Move the docs from https://github.com/containerd/containerd/tree/main/docs into this repo, as suggested in:
   • move the doc from containerd/contaienrd to contaienrd/containerd.io #97
   • Merge this repo into main repo? (or vice versa) #80 (comment)
2. Leave the docs in the containerd code repo, but bring them in here via a git submodule.

Each method has its pros and cons. The simplest method (for all contributors and maintainers) is the first, but the second is preferable IMHO to redirecting readers to a GH repo.

Either of the solutions above are preferable, IMHO, to say, client-side rendering as was recently proposed in #149.

/cc @nate-double-u @caniszczyk

[suyanhanx]

In the current situation, I think it would be good to merge it into the main repo.
Many projects under containerd put their docs directly in the repo.

But it might need to be migrated to Vercel.
Netlify need to add [skip netlify] to PR title or commit message to skip compilation. This is very annoying.
But Vercel can run some commands to decide whether to skip it or not.

reference:

1. Vercel doc about skip build
2. an example about skip build in Vercel

[chalin]

Since the website repo already exists (and the build - deploy mechanisms already in place), and if you insist on keeping the docs in the code repo, then why not give option (2) above a try? As you mentioned elsewhere, we can then setup a GH action to push submodule updates to this repo when the docs change in the code repo.

[suyanhanx]

I will try option (2) soon. That's what I was thinking before.

[estesp]

The attempt in #121 was a start along the path of option 2; it just has never been completed as it needs some additional effort to make sure we don't end up with duplication/or filter out any docs that don't make sense on the website (maybe none? but this is mostly a management/admin issue of making sure that the docs/ directory in the project GitHub is all in good shape for consumption on the website as an official project document)

I think we are definitely leaning (as a project; I'm one of several maintainers) towards continuing to have the docs/ directory in the main project be our document source and would love to find the best way to have them reflected here on the website in a way that is attractive and doesn't appear clunky or poorly aligned with the site's design/layout.

[suyanhanx]

I think the number of documents is already a lot at the moment.
Now, if we sync docs to this repo, we also need to adjust the document directory's structure or the layout of the website to show so many documents.

May we clean up, for example, outdated documents first?

[mikebrow]

I think the number of documents is already a lot at the moment. Now, if we sync docs to this repo, we also need to adjust the document directory's structure or the layout of the website to show so many documents.

May we clean up, for example, outdated documents first?

Need a rough process.. for updating and confirming what docs are up to/out of date by release version.

Seems fair to have an issue with task items split up for confirming docs with each major release.

The results of which could also be stored in an index file (outlining all the docs), or appendix/version.md.

[suyanhanx]

Seems fair to have an issue with task items split up for confirming docs with each major release.

We can take a snapshot of the website for each major release.

And I think we can make a GitHub action to proactively push updates to the website by checking for updates of the docs folder in the containerd repo. If this is done, it will also reduce unnecessary synchronization actions.

[haddscot]

checking in on this since it's been over a year since the last comment on this issue
can I ask what advantages we see in the option to clone and rehost documentation on the .io site rather than simply
(a) embedding the markdown on the docs page, or
(b) eliminating the docs pages and instead linking directly to the GH documentation from the dropdown menu?
that way we don't need to worry about keeping things synchronized since we'll be pointing people towards the source of truth directly.

[haddscot]

mkdocs is also an interesting option: https://github.com/mkdocs/mkdocs

if we can implement the document syncing, then mkdocs can generate the static content for the site.

I think I'll implement

(b) eliminating the docs pages and instead linking directly to the GH documentation from the dropdown menu

first, but I'll start looking into document syncing and mkdocs as a long term version

[haddscot]

it looks like there's already a pretty decent implementation underway here: #121

gonna close this issue as a duplicate and develop on top of the work done in #121