Supersedes #94, #126

As per the conversation around the Etcd.io Docs/SEO Improvement Plan:

• Plan docsy migration docsy prep work #126
  • Is Docsy migration still warranted? (after some cleanup and migration of docs to the website, is it still the best option? What about Docusaurus?)

Initial docsy conversion

• Generate site using the Docsy Example site etcd.io docsy conversion #112
• Pull in Documentation as is etcd.io docsy conversion #112
  • Move Documentation to content/en folder etcd.io docsy conversion #112
  • Ensure no links/bookmarks are broken in the conversion process
• Ensure front page content created is the same as the original page etcd.io docsy conversion #112
  • Page structure allows for upcoming changes as per the new information architecture
• Ensure site builds etcd.io docsy conversion #112
  • locally (make serve, using hugo serve)
  • locally (docker-compose up --build)
  • netlify
• update README README: update / drop "releasing a new version of docs" section #144
• Ensure that existing functionality is not lost
  • Versions
    • Add warnings to DRAFT and DEPRECATED pages Add warnings to DRAFT and DEPRECATED pages #236
  • Apply empty href fix to docsy branch (see: Link checking: why do we have empty hrefs? #180) Link checking: remove empty hrefs (docsy branch) #198
• Prepare for internationalization
  • Bring in language safe version selector from PoC Ensure that only the docs for actively selected version show up in the side-nav #135 etcd.io docsy conversion #112
  • Ensure versioning system works with i10n system
    Proof of concept work here shows an older rev of our versioning system working with languages: https://deploy-preview-1--jolly-albattani-baa029.netlify.app/
    https://deploy-preview-1--jolly-albattani-baa029.netlify.app/docs/current/ <-- English
    https://deploy-preview-1--jolly-albattani-baa029.netlify.app/no/docs/current/ <-- Norsk

Min items before initial merge (milestone):

• Ensure the homepage looks like (or better than) the original homepage Ensure the homepage looks like (or better than) the original homepage #215
• Footer: the "user" and "developer" links should refer to etcd resources Footer: the "user" and "developer" links should refer to etcd resources #228
• (Minor) Also use the compact section listing format for the "Next docs" page Format next's landing page like all other doc vers landing pages #231
• Add etcd favicon Add etcd favicon #232
• Create a custom 404 page Create a custom 404 page #238

Post-docsy conversion (milestone): items have been moved to #247

• Ensure that the branch name in the config file is switched back to master
• (Minor) Fix broken internal links: latest Drop About from docsy MVP, and make link checker happy #227
• Versions menu shouldn't take up real estate in the top nav if it isn't being shown
• Consider reintroducing page descriptions on version landing pages as part of IA discussion
• Automatic page generation is preserved (see Ensure that generated documentation gets merged into website automatically (etcd-io/website) #111 & Ensure that generated documentation gets merged into website automatically etcd#12768)
• List of generated metrics files (as per conversation Move historic metrics files #171 (comment)) Reinstate metrics #242
• Clean out any unused assets, layouts, etc from the pre-docsy version of the site
• Footer: copyright date range should match license file
• Check if we still need specific files after initial docsy-conversion Check for obsolete files after initial docsy-conversion #139
• Setup Blog URL Permalinks Setup Blog URL Permalinks #140
• Ensure that author names appear in blog entries

prep work

• Create a docsy branch
  • Add docsy submodule Add docsy submodule without using it #125
  • Consider: Move site pages into content/en etcd.io docsy conversion #112

Cleanup

• Ensure that only the docs for actively selected version show up in the side-nav Ensure that only the docs for actively selected version show up in the side-nav #135
• Footer: streamline and bring closer to updated CNCF website guidelines Footer: streamline and bring closer to updated CNCF website guidelines #137 New footer and version-selector; also fixes empty hrefs #207
• Use a Netlify _redirects file to hold redirects Use a Netlify _redirects file to hold redirects #138

Suggested process for working with the docsy branch:

• We can now implement the Docsy conversion (Convert to Docsy #94) incrementally by submitting commits and PRs over the docsy branch.
  • Issues and PRs for the docsy branch should be tagged with the docsy label and/or have their title prefixed with [docsy]
• IMPORTANT: when accepting PRs over the docsy branch, use Squash and merge
• IMPORTANT: when updating the docsy branch relative to master, do a rebase not a merge.
  • Ideally, such a rebase should only be done when there are no PRs open over docsy

Also:

• Ensure that a production deploy of the docsy branch, once we reach that point, is indexable by search engines.