docs: refactoring and cleanup #1658
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- use Hugo `ref` helper to resolve cross-links - delete a renaming fragment (from go-acme#1487) - replace placeholder email addresses (foo@bar.com → you@example.com)
- split examples into multiple pages - restructure content a bit - flesh out some sections - add a section about load spikes (cf. go-acme#1656)
Also use "you@example.com" instead of various other example email addresses.
- hoist meta data into (generated) frontmatter - use a custom Hugo shortcode to render DNS providers in tabular form
Splitting the content in multiple sub-sites broke links. By keeping it hidden, this site serves as a soft-redirect landing page. The user won't immediately find the information an external site might have hyperlinkes, but a short summary of gives the user a fast overview on where to continue.
|
I'm now satisfied with the result and I have updated the PR description. I tried to keep the commits small, but changes on the |
ldez
requested changes
Jun 16, 2022
Co-authored-by: Ludovic Fernandez <ldez@users.noreply.github.com>
ldez
approved these changes
Jun 16, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I just wanted to add a small section about being a good netizen (for #1656), but ended up splitting the CLI usage examples into easier digestible parts.
By doing so
usage/cli/examples/would have been gone, and direct links (think: bookmarks) would yield a 404 Not Found error. Github Pages doesn't allow redirects (apart from ugly hacks involving<meta http-equiv="refresh" content="0; URL=...">), so I've kept the examples page as a landing page, but hidden from the main menu. Users following a direct link can use it reorient themselves.Screenshot
I've also updated, changed, harmonized and reshuffled a lot of things:
Markdown links now use Hugo's cross reference helpers to resolve the target (
[text](usage/cli#port-usage)→[text]({{< ref "usage/cli" >}})).dns/softlayer/was redundant and I have removed it. I assumed this was overseen when refactoring PR Add DNS Provider for IBM Cloud (SoftLayer) #1487.the CLI examples now consistently use long-form flags (
--emailinstead of-m)example email addresses are now consistent (
you@example.com)usage/dns/manual/looked borked, I've recreated the exampleI've added a link to Github discussions to the sidebar
the main body width is now constricted to max. 72em. I'm using a high-resolution, wide-screen monitor and now the text is not thinned over the whole screen. For resolutions less than ~1400px not much will change
Screenshot
The generated DNS provider files have now some meta data in their frontmatter. Using this meta data, I have reformatted the provider listing on
dns/#dns-providers:Screenshot
For easier comparison, I've uploaded the generated site to https://mm.dmke.org/lego/