etcd-io / website

etcd.io

etcd.io

The etcd.io website, built using Hugo and hosted on Netlify.

Cloud build

Visit https://gitpod.io/#https://github.com/etcd-io/website to launch a Gitpod.io IDE that will allow you to build, preview and make changes to this repo.

Local build

To build and serve the site, you'll need the latest LTS release of Node. Like Netlify, we use nvm, the Node Version Manager, to install and manage Node versions:

$ nvm install --lts

Setup

1. Clone this repo.
2. From a terminal window, change to the cloned repo directory.
3. Get NPM packages and git submodules, including the the Docsy theme:

   $ npm install

Build or serve the site

To locally serve the site at localhost:8888, run the following command:

$ npm run serve

NOTE: If you want to check links locally, you (temporarily) might have some extra setup to do. For details, see issue #459.

To build and check links, run these commands:

$ npm run build
$ npm run check-links

Contributing

We welcome issues and PRs! For details, see Contributing.

If you submit a PR, Netlify will automatically create a deploy preview so that you can view your changes. Once merged, Netlify automatically deploys to the production site etcd.io.

Releasing a new version of the etcd documentation

IMPORTANT: this section is out-of-date, see issue #406.

Follow these steps to add documentation for a newly released version of etcd, vX.Y:

• Recursively copy content/docs/next into content/docs/vX.Y, where vX.Y is the newly released version of etcd. For example:

  cp -r content/docs/next content/docs/v3.5

• In the _index.md file at the root of the new directory, update the frontmatter to reflect the new version:

  ---
  title: etcd version X.Y
  weight: 1000
  cascade:
    version: vX.Y
  ---
  

• Add the version to the params.versions.all array in the config.toml configuration file.

• If the version is meant to be the latest version of etcd, change the params.latest_stable_version parameter to the desired new version.

• Submit a pull request with the changes.

website's Issues

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

Originally posted by @Stale in etcd-io/etcd#11357 (comment)

[Netlify] Alert: Insecure mixed content detected in etcd

Insecure mixed content detected

Message from Netlify:

Although you have enabled HTTPS on your site, we’ve detected some content that’s still being served over an HTTP connection. This phenomenon, called mixed content, happens when both HTTP and HTTPS are being used to load the same page.

Mixed content impacts the security and user experience of your site, and prevents browsers from protecting your users from malicious attacks.

We’ve added some information to your deploy log to help you find the problem. Most major browsers also provide tools to help you find and fix mixed content. They alert you about mixed content in the JavaScript console. To find this console, you can right-click in any page of your site, select “Inspect Element”, and then select “Console”.

Google’s Developer Guides provide a more extensive description about this problem and its solution.

See full deploy logs

Use a Netlify _redirects file to hold redirects

An advantage of using a Netlify _redirects file over putting redirect rules in a netlify.toml, is that you can now use the full power of Hugo's templating language to generate all or part of the contents programmatically. E.g., see https://github.com/grpc/grpc.io/blob/main/layouts/index.redirects.

Decommission CoreOS etcd site

The docs in the website are all leading to etcd version 2, links to version 3 are broken

When I go to the documentation of etcd3 I expect to find the most updated docs, older versions should be easy to find.
Currently, the default is documentation of etcd2

The links to updated documentation are broken:

Convert to Docsy theme

Supersedes #94, #126

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

• Plan docsy migration #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 #112
• Pull in Documentation as is #112
  • Move Documentation to content/en folder #112
  • Ensure no links/bookmarks are broken in the conversion process
• Ensure front page content created is the same as the original page #112
  • Page structure allows for upcoming changes as per the new information architecture
• Ensure site builds #112
  • locally (make serve, using hugo serve)
  • locally (docker-compose up --build)
  • netlify
• update README #144
• Ensure that existing functionality is not lost
  • Versions
    • Add warnings to DRAFT and DEPRECATED pages #236
  • Apply empty href fix to docsy branch (see: #180) #198
• Prepare for internationalization
  • Bring in language safe version selector from PoC #135 #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 #215
• 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 #231
• Add etcd favicon #232
• 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 #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 #111 & etcd-io/etcd#12768)
• List of generated metrics files (as per conversation #171 (comment)) #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 #139
• Setup Blog URL Permalinks #140
• Ensure that author names appear in blog entries

---

prep work

• Create a docsy branch
  • Add docsy submodule #125
  • Consider: Move site pages into content/en #112

Cleanup

• 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 #137 #207
• Use a Netlify _redirects file to hold redirects #138

---

Suggested process for working with the docsy branch:

• We can now implement the Docsy conversion (#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.

better adopters copy

• point the link to https://github.com/etcd-io/etcd/blob/master/Documentation/production-users.md and https://github.com/etcd-io/etcd/blob/master/Documentation/integrations.md
• Highlight projects like m3, rook, patroni, trillian, coredns, and openstack instead of Cloud Foundry (which doesn't use it anymore AFAIK)

Etcd.io Docs/SEO Improvement Plan

I've been looking over the current etcd website and documentation, and feel that a refactor is warranted in order to improve them. Over the next few months, I plan to commit a significant part of my personal time to doing the below; I'm looking for the project's approval that these are all things that should get done. I also have the support of CNCF's web designer to help with this.

Objectives

To make etcd.io the primary destination for information about how to run, deploy, maintain, and scale etcd, both as a real resource and via search engines.

What's Working

The etcd documentation is automatically built based on the sources in the main development repository, so that we have regular updates when new versions are released. We have fully browesable per-version documentation that contains a lot of information about etcd code and internals.

What's Not Working

Currently etcd.io is often not the first hit when searching on common etcd tasks, such as "etcd setup", "how can I scale etcd", or "etcd troubleshooting". Instead, various random other pages are, some associated with our project (such as the CNCF blog) and some not (Rancher.com or Portworx pages). Importantly, because the most findable sources are not part of the official etcd documentation, the information on them is often out of date.

Part of the reason for this is that the existing documentation is not very browseable, and is structured in a way to give it poor SEO. It is also difficult for beginning users to find what they need. This is something that we can fix.

Improvement Plan

Short Term

Home Page Improvements

Add the following static pages to the website, linked off a section on the home page:

• Documentation TOC - page with an annotated TOC for the documentation and direct links to important pages.
• Download Etcd - page with links to sources, packages, and containers for getting Etcd and installing it (cross-link to 3,4)
• Getting Started with Etcdctl - page with simple instructions on how to install and get started with Etcdctl, including authentication to existing clusters.
• Getting Started with Etcd - page with simple, 80% solution, instructions on installing Etcd on a Linux server.
• Troubleshooting Etcd - page with lots of links to things like how to analyze errors, how to file a bug, etc. Add links to relevant blog posts as they get written.

Each of these static pages will live in the website repo rather than docs; as much as possible they will be somewhat version-agnostic. All basics will be covered on the static page, with links off of them only for more in-depth review or unusual circumstances (e.g. "etcdctl kerberos authentication").

Documentation Content

Replace TOC for documentation navigation with one that makes more logical sense from a "user journey" point of view. This will be the same TOC displayed on the static page. At a top level, this would mean replacing the existing sections with the following:

• Getting Started (some of which links back to static pages, or copies of those pages)
• Administration (Operations Guide + Upgrading + Platforms + some other pages which are operational, like Metrics)
• Developer Guide (Developer guide + Learning Etcd)
• Contributor Guide (Currently would include Reporting Bugs and Issue Triage, but more content later)
• Additional Information (FAQ + Benchmarking + some other pages)

Each section will be reworked so that it follows some kind of logical order, for example from installation, to growing the cluster, to upgrading. Note that this may require adding additional required header information into existing documentation files.

We also need to fix multi-version navigation. That is, switching "versions" of the documentation should automatically navigate to that page in the selected version of the docs, if that page exists. If this is challenging to do with the documentation toolchain we have, re-evaluate whether we want to keep versioned documentation.

Blog

Encourage weekly blog posts of unique content, mostly alternating how-to articles and release updates (patches, etc.). The new content here will drive some traffic as well as supply material for future documentation.

Cleanup

Fix 404s: we have a lot of lost pages. These need to get replaced with redirects.
Shorten redirect chains (not sure how many of these we have)
Add a Documentation tag to both the Etcd and Website repos so that we can start tracking docs issues.

Ongoing/Long Term

Blog Transfer

As we accumulate extra "How To" information into our blog, this content will be reworked in order to create a "Solutions" section for the documentation. This will be like the Tasks section in the Kubernetes documentation. Such solution-oriented documentation tends to attract links from developer sites. To the extent possible, to support this, we will develop and maintain a "blogs wanted" list of solutions for which we'd like a blog post.
Documentation Content

Add a review checklist of documentation pages to be reviewed with each version release. This helps prevent staleness and inaccuracy. Or, if we don't have time to review them, at least we have a TODO list for contributors.

Build out the contributor section, encompassing the information in Contributing.md, and add information specifically about contributing to the documentation.
Create and build out a Solutions section per the above.

Documentation Contributors

Launch a long-term campaign to attract documentation-only contributors in order to reduce burden on the primary maintainers. Such a campaign would include:

• Clear documentation on how to contribute to the docs.
• Ensuring that documentation patches get reviewed and applied (or rejected).
• A path to documentation contribution seniority/authority, so that doc contributors can review doc contributions.
• Doc sprint events at Kubecon and/or WriteTheDocs

Check for obsolete files after initial docsy-conversion

Question about whether or not we need some files still (some came in on a recent rebase)

Can we remove the following (check for yes, we can remove them):

• layouts/_default/_markup/render-link.html. Keep, but fix: #270
• layouts/partials/css.html #388
• layouts/robots.txt
• layouts/404.html, keep as is (should we use the docsy default?)
• package-lock.json
• static/apispec/swagger (the whole folder, @spzala?) #388

Positive answers to this (i.e. the file should be removed) doesn't have to stop this PR from being merged, we can just open an issue against the docsy branch if we need to take action.

Originally posted by @nate-double-u in #112 (comment)

Convert to Docsy

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

• Plan docsy migration #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?)

---

• Generate site using the Docsy Example site
• Pull in Documentation as is
  • Move Documentation to content/en folder
  • Ensure no links/bookmarks are broken in the conversion process
• Ensure front page content created is the same as the original page
• Ensure site builds
  • locally (make serve, using hugo serve)
  • locally (docker-compose up --build)
  • netlify
  • update README
• Ensure the front page looks like the original page
• Ensure that existing functionality is not lost
  • Versions
  • Automatically page generation is preserved (see #111 & etcd-io/etcd#12768)
• Prepare for internationalization
  • Add front page copy to language file/param
  • Ensure versioning system works with i10n system

---

Possible prep work

• Create a docsy branch
  • Add docsy submodule #125
  • Consider: Move site pages into content/en

website pageview analytics

To help figure out the effectiveness of the etcd documentation and marketing pages we need to provide analytics such as page views, bounce rates, time on page, and geographic information.

Setup Blog URL Permalinks

Originally posted by @chalin in #112 (comment)

There are several ways to set up the blog URL permalinks

• discuss best method for this site
• set [permalinks] blog variable in config.toml based on discussion

docsy prep work

• Add docsy module from cncf/docsy repo, pinned to the etcd.io branch. @chalin --> #125
• Merge #124 and #125 in that order. @nate-double-u
• Create a branch named docsy. This is the branch against which we'll be creating docsy-related PRs. @nate-double-u
• Update the Netlify config so that previews are automatically built for the docsy branch. #127 #128 @nate-double-u
• Create a docsy label so that we can tag docsy-specific issues and PRs. @nate-double-u

Suggested process for working with the docsy branch:

• We can now implement the Docsy conversion (#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.

move etcd.io domain maintenance to the CNCF

Dependencies:

• Discovery.etcd.io owned by CNCF

Footer: streamline and bring closer to updated CNCF website guidelines

Streamline the website footer and bring it closer to the updated CNCF website guidelines. As an example of this see grpc/grpc.io#716.

This can be done before and/or after #134.

Client feature matrix: link-only section headings cause problems

Most section headings in Client feature matrix (v3.3.12) and Client feature matrix (v3.3.13) are links to corresponding API pages. For example, see https://github.com/etcd-io/website/blame/master/content/docs/v3.3.12/learning/client-feature-matrix.md#L23:

## [KV](https://godoc.org/go.etcd.io/etcd/clientv3#KV)

Generally speaking, this isn't good practice.

Specifically in our case, it causes the following problems under more recent versions of Hugo (#113) and when the site is built with docsy (#94):

• If you click a Table-Of-Contents (TOC) entry, like KV, you're redirected to an API page, rather than jumping to the corresponding in-page heading.
• Rendered heading anchors are unintuitive -- e.g., like #kvhttpsgodocorggoetcdioetcdclientv3kv rather than #kv.

cc @nate-double-u @zacharysarah

---

dead link

This link is currently 404 https://etcd.io/docs/v3.3.12/metrics/v2/metrics.md#http-requests

Also broken on the most current version https://etcd.io/docs/v3.4.0/metrics/v2/metrics.md#http-requests

Documentation Content: TOC

As per the Documentation Content Section of the Etcd.io Docs/SEO Improvement Plan

• Replace TOC for documentation navigation with one that makes more logical sense from a "user journey" point of view.
• This will be the same TOC displayed on the static page.

At a top level, this would mean replacing the existing sections with the following:

• Getting Started (some of which links back to static pages, or copies of those pages) #278
• Administration (Operations Guide + Upgrading + Platforms + some other pages which are operational, like Metrics)
• Developer Guide (Developer guide + Learning Etcd)
• Contributor Guide (Currently would include Reporting Bugs and Issue Triage, but more content later)
• Additional Information (FAQ + Benchmarking + some other pages)

Sections

• Each section will be reworked so that it follows some kind of logical order, for example from installation, to growing the cluster, to upgrading.
  Note: that this may require adding additional required header information into existing documentation files.
• etcd documentations files have been reworked for order and annotations.
• Preview https://deploy-preview-83--etcd.netlify.app/docs/current/
• PRs: etcd-io/etcd#12509 & etcd-io/etcd#12575

Note from ZC: "bucket information more intentionally around a concepts, tasks, and tutorials model."

Information Architecture

Original IA: https://miro.com/app/board/o9J_lX9eUAg=/
Proposed IA: https://miro.com/app/board/o9J_lWnPo9c=/

Render-link hook generates unnecessary whitespace

For example, consider this excerpt from Docs > Operations guide > Configuration flags > Clustering flags:

Notice the extra space after the opening parentheses in "( static ...)".

cc @nate-double-u

Related: grpc/grpc.io#202

Multiple Broken Links across the site

There are multiple broken links across the site. I am working on fixing them. I have fixed most of external links.

Here's the current state of broken links -
https://docs.google.com/spreadsheets/d/10FXHFFzSJy4NvezabBPvS5Bm8z3WhVQclz0RxI_aDUo/edit?usp=sharing

I could not find the links for the ones highlighted in red.

I am working on fixing remaining links.

Dead link: Member data migration

Several links are broken on this page referencing the admin guide for migrating the data directory (appears to be present in v2, but not newer versions, not sure if that's still up to date)

https://etcd.io/docs/v3.3.13/op-guide/runtime-configuration/

Migrate etcd docs to website repo

Migrate the content of https://github.com/etcd-io/etcd/tree/master/docs to this new repo. Adding more details later working with @gyuho

Documentation : dead link in https://etcd.io/docs/v3.3.12/integrations

https://etcd.io/docs/v3.3.12/integrations

deadlink : https://etcd.io/docs/v3.3.12/raft/README.md#notable-users

refresh changs value when does not set value

website doc "You cannot update the value of a key when refreshing it."

$ curl http://127.0.0.1:2379/v2/keys/foo -XPUT -d value=bar -d ttl=60
{
"action":"set",
"node":{
"key":"/foo",
"value":"bar",
"expiration":"2020-09-24T02:17:05.5974668Z",
"ttl":60,
"modifiedIndex":12038,
"createdIndex":12038
}
}

$ curl http://127.0.0.1:2379/v2/keys/foo -XPUT -d ttl=60 -d refresh=true -d prevExist=true

{
"action":"update",
"node":{
"key":"/foo",
"value":"", // node value refreshed with blank string
"expiration":"2020-09-24T02:17:18.6460187Z",
"ttl":60,
"modifiedIndex":12039,
"createdIndex":12038
},
"prevNode":{
"key":"/foo",
"value":"bar",
"expiration":"2020-09-24T02:17:05.5974668Z",
"ttl":47,
"modifiedIndex":12038,
"createdIndex":12038
}
}

Versioning: switching between versions on some (known existing) pages generates 404 error

We are seeing 404s when switching between versions on some (known existing) pages.

Some files in v3.4.0 have had their names changed from using _s to using -s, and this is causing 404s when switching between the older versions and the latest one.

Known files (this may not be a complete list):

• Branch Management
  content/docs/v3.4.0/branch-management.md
content/docs/v3.3.13/branch_management.md
  https://etcd.io/docs/v3.4.0/branch-management/
  https://etcd.io/docs/v3.3.13/branch_management/
• Reporting Bugs
  content/docs/v3.4.0/reporting-bugs.md
content/docs/v3.3.13/reporting_bugs.md
  https://etcd.io/docs/v3.4.0/reporting-bugs/
  https://etcd.io/docs/v3.3.13/reporting_bugs/

Proposed fix:
Rename v3.4.0 files to use _ instead of - to match previous versions.

This fix may need to be propagated to the Documentation files in etcd-io/etcd as well.

Ensure that generated documentation gets merged into website automatically (etcd-io/website)

As per the discussion in the March 11, 2021 etcd public meeting, we need to ensure that generated documentation gets merged into website automatically on update.

Opening an issue in the website repo as well in case we need to make any changes here as well.

Related issues:

• etcd-io/etcd companion to this issue: Ensure that generated documentation gets merged into website automatically #12768
• Etcd.io Docs/SEO Improvement Plan #65

/cc @hexfusion, @ptabor, @spzala

top logo on docs goes to etcd.netlify.com

See title

@lucperkins

versioned documentation

Like the existing etcd docs website we should have versioned documentation. Copying and/or using the existing docs setup exactly isn't necessary. The only thing is the outcome of the setup: etcd docs that are partitioned by version.

e.g. https://coreos.com/etcd/docs/3.2.13/index.html
v.s. https://coreos.com/etcd/docs/latest/

We can use whatever tooling to accomplish this. So, if there is another CNCF project doing this you can copy and use that infrastructure.

Add 3.3.13 docs

@lucperkins are there docs on how to add a new release docs to the site?

https://github.com/etcd-io/etcd/releases/tag/v3.3.13

cc @gyuho

Migrate documentation: Remove docs from etcd-io/etcd

Description

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

Replace existing documentation in etcd-io/etcd repo with signposts to new location on website (etcd.io).

Deliverable

etcd-io/etcd Documentation folder points to etcd.io/docs

Notes

• Since we agreed that issues related to the etcd.io Docs/SEO Improvement Plan should be made in the etcd-io/website repo, this issue is being created here even though it affects etcd-io/etcd

• The pull request for this issue will be made in etcd-io/etcd

• The pull request for this issue in etcd-io/etcd should not be merged until the PR for Migrate documentation: Add docs to etcd-io/website #93 has been merged. PR #99

• https://docs.google.com/spreadsheets/d/1-ZQMPc_eQ0fh1pwOHv3NltwT-ifKA5UcFePfdFiWn8I/edit?usp=sharing

Add LICENSE

The etcd-io/etcd repo is licensed under Apache 2.0.

I suggest we both license the website under Apache 2.0, and the documentation under CC-BY-4.0.

I like how the Keptn project has done this in their website repo, adding 2 LICENSE files, one for the site, the other for docs, and explaining it in their README file.

complete index on docs homepage

https://etcd.netlify.com/docs/v3.3.12/

It would be nice if the root docs page included an index of the sections instead of an index for the root sections.

e.g.

• Old: Download and build, Libraries and tools, Branch management, ...
• New: Benchmarks, Developer Guide, Learning, ...

Remove .lock files

We'll be rebasing often, and I've found it a pain to rebase .lock files.

Actually, IMHO it isn't worth the headache of committing a .lock file for websites. In the case of etcd.io we only have a small set of dev dependencies. My suggestion would be to drop the .lock file from master, and propagate that change to here.

Originally posted by @chalin in #112 (comment)

Use latest version of Hugo to build the site

As of the time of creating this issue, the latest release is 0.81.0. The currently used version, 0.65.0, is too old for docsy@HEAD.

cc @nate-double-u -- let's discuss an upgrade strategy.

Update the Netlify config so that previews are automatically built for the docsy branch

Update the Netlify config so that previews are automatically built for the docsy branch, ensuring that the docsy branch is not indexed by search engines.

Contributes to: #126, #94

/cc @chalin

Docs for AWS say "across at least two AZs", shouldn't that be three?

In the "Availability" section of https://etcd.io/docs/v3.4.0/platforms/aws/

In the context of an etcd cluster this means a cluster must contain a minimum of three members where EC2 instances are spread across at least two AZs in order for an etcd cluster to be considered highly available at a Regional level.

If we spread our three etcd nodes across two AZs, then one AZ will have two nodes. If that AZ goes down, etcd will be completely unavailable, right?

Am I misunderstanding the terms here?

Migrate documentation: Site cleanup / prep

Description

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

Cleanup the existing site architecture (Bring prose out of config files, layout files, etc., and make the site generally more hugo-like)

Deliverable

Site prepared for Docsy conversion

Notes

• https://docs.google.com/spreadsheets/d/1-ZQMPc_eQ0fh1pwOHv3NltwT-ifKA5UcFePfdFiWn8I/edit?usp=sharing

not existing option `discovery-srv-name` is in the docs for 3.3.13 and .12

This option is described in the docs, but not supported in reality. Please check discussion here: etcd-io/etcd#10916

Cleanup

As per the Cleanup Section of the Etcd.io Docs/SEO Improvement Plan

• 1. Fix 404s: we have a lot of lost pages. These need to get replaced with redirects.
• 2. Shorten redirect chains (not sure how many of these we have)
• 3. Add a Documentation tag to both the Etcd and Website repos so that we can start tracking docs issues.
  • etcd-io/website
  • etcd-io/etcd

Client feature matrix: copyedits, link updates, and CSS cleanup needed

This is a followup to #114 & #118.

As a general rule, we shouldn't embed raw links in the documents -- unless the raw link is part of the document content (such as providing a sample URL).

My suggestions are, for each page, and each section:

• Remove the raw URL and instead add text like the following after the feature table:

  For details, see the KV API reference.

• Update all links that refer to godoc.org. E.g.:

  • From: https://godoc.org/go.etcd.io/etcd/clientv3#KV
  • To: https://pkg.go.dev/go.etcd.io/etcd/clientv3#KV

• Globally search-and-replace the unnecessary left-indent syntax in the table Markup: left-indentation is the default, and adding the extra syntax causes redundant CSS to be generated. E.g.,

  • Replace:
    :-------|:--------------------|:--------------
  • With:
    --------|---------------------|---------------

cc @spzala @zacharysarah

crowded on 800x600 display

Should probably just transition to the mobile hamburger style at 800x600 as the nav is nearly half the screen.

sidebar anchor heirarchy

The sidebar links don't have any heirarchy and can be confusing to understand. See the FAQ page for example:

https://deploy-preview-16--etcd.netlify.com/docs/v3.3.12/faq/#what-is-the-difference-between-listen-client-peer-urls-advertise-client-urls-or-initial-advertise-peer-urls

Ensure that only the docs for actively selected version show up in the side-nav

Contributes to #134

Migrate documentation: Manage generated docs in etcd-io/ectd

Description

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

Find out which docs are generated, how generated docs work, and how they're linked to the rest of the documentation and ensure a path for publication on etcd.io.

Deliverable

Generated docs on etcd.io site linked into navigation. Instructions set on how to generate in future versions.

Notes

• Related issue: #93
• #65 (comment)
• https://docs.google.com/spreadsheets/d/1-ZQMPc_eQ0fh1pwOHv3NltwT-ifKA5UcFePfdFiWn8I/edit?usp=sharing

Migrate documentation: Add docs to etcd-io/website

Description

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

Migrate the canonical documentation from the etcd-io/etcd repo to this repo.

Deliverable

etcd.io has a new current version based on documentation from etcd-io/etcd. Subsequent versioning/releases can use this as base.

Notes

• (from @ptabor), some of the documentation is autogenerated.
• https://docs.google.com/spreadsheets/d/1-ZQMPc_eQ0fh1pwOHv3NltwT-ifKA5UcFePfdFiWn8I/edit?usp=sharing

Images not found in etcd docs

Images are not found in this etcd doc

Documentation Content: Versioning

As per the Documentation Content Section of the Etcd.io Docs/SEO Improvement Plan

• Fix multi-version navigation
  • That is, switching "versions" of the documentation should automatically navigate to that page in the selected version of the docs, if that page exists.
  • If this is challenging to do with the documentation toolchain we have, re-evaluate whether we want to keep versioned documentation.

FAQ broken link

the FAQ link [faq.md] is broken on readme.md. It is expecting a faq.md at: etcd.io/docs/v3.4.0/v2/readme/faq.md

RFC: New Information Architecture

As per the conversation around the Etcd.io Docs/SEO Improvement Plan, I've put together an Information Architecture to help guide the website changes and development of new pages on the site. I'm sharing it here as we discussed in the March 11, 2021 etcd public meeting to invite comment and critique.

Proposed Information Architecture: https://miro.com/app/board/o9J_lWnPo9c=/
(I've also put together a diagram of the site's current information architecture if you'd like to compare/contrast).

The idea behind the 4 top level branches are:

• Evaluation: What is this product, is it right for me, what problem does it solve, and how will I know?
  • Sample section titles: Overview, Getting Started, Reference, Community
• Addition: How do I build solutions?
  • Section titles: API reference
• Fix: How do I fix problems I encounter?
  • Section titles: troubleshooting, FAQ
• Features: How do I build new features and contribute to the project?
  • Section titles: Contributing

(Thanks @zacharysarah for helping me map these)

Broken links

While switching to a different version in some cases, the resulting link gives 404 error.
For example, try to open any version (e.g. v3.4.0) from https://etcd.io/docs/v2/backward_compatibility/ The resulting link https://etcd.io/docs/v3.4.0/backward_compatibility/ is broken.

/cc @nate-double-u