docs(basics): update documentation for first-time users

[jamesericdavidson]

Summary

This PR aims to:

• Fix any errors in the text, hyperlinks, etc.

• Make text concise, while ensuring the documentation is appropriate for first-time Hugo users

  Existing users can skip over the text, and don't need unmodified concepts re-introduced to them.

• Distinguish between standard Hugo concepts (which Gokarna implements), and bespoke Gokarna features which do not follow Hugo standards

Work applies to Theme Documentation - Basics only. Advanced is unaffected, though Basics will continue linking to Advanced when appropriate.

N.B. Meaningful content changes are denoted in commits with the docs: message prefix.

To Do

• [x] Write a summary of important changes
• [x] First pass of config.toml
• [x] First pass of Basics
• [x] Add consistent subheading links (anchors) {#my-heading} where appropriate (e.g. b. Install the Theme)
• [x] Ignore exampleSite/public/ when building with hugo serve (useful for anyone working on upstream Gokarna, or forks!)
• [x] fix: toggleNext must be a string (cannot eval true/false as bool)
• [x] style: encapsulate favicon file names in backticks
• Make description's function as a meta description clearer for non-post content:
  • [x] Home page
• [x] Exemplify that the sample config.toml uses Gokarna's default values, while param-specific documentation uses exampleSite's config.toml
• [x] Order params/subheadings alphabetically
• [x] Add note: backToTop is not seen on mobile (does CSS define px? Min screen size - laptop, tablet?)
• [x] Generally include more links to explain Hugo concepts (e.g. https://gohugo.io/getting-started/configuration/#all-configuration-settings), web dev concepts (MDN), etc.
• [x] Include docs for #241 (if merged)
• [x] Include docs for #242 (if merged) There will be breakage if #243 is merged before #241 or #242 (and vice versa!)
• [x] Final pass & open for review

Removed

• First pass of Advanced Delay work to separate PR
• Advanced: Re-order custom HTML subheadings Delay work to separate PR
• Home page content is replicated in Advanced Delay work to separate PR
• Issue 1 overhaul Consider for PR after Advanced
• Issue 2 overhaul Consider for PR after Advanced
• Weight is replicated in the Advanced section ? Delay work to separate PR
  • Include prev-next warning Delay work to separate PR
• Create Your First Post: Mention archetype first (doc duplication?), then propose manual YAML insertion for post kind Every user will have access to archetypes, this is unnecessary to document in Gokarna
• When using archetype: Link to Table of Contents, and mention setting to true if wanted This is already covered in advanced and shouldn't be replicated?
• Explain how title is derived from file name (already included in #241 docs)
• Description: index.md ? We don't recommend using front matter in index
• Always identify Hugo standard features vs. bespoke Gokarna features Done implicitly
• feat: mention installing Hugo (not just Gokarna) not relevant
• feat: link to markdown guide not relevant
• Make description's function as a meta description clearer for non-post content: Pages not suitable for Basics
• Expand accentColor's role, as per MDN https://developer.mozilla.org/en-US/docs/Web/CSS/accent-color unnecessary

Issues (for later PRs)

1. Comments are often replicated between Basic Configuration, Configuration and individual params with little additional content, context, or links provided for further reading

   DRY. Only expand on the param if beneficial to the user, otherwise remove other instances of that feature's documentation (e.g. if the short comment in Basic Configuration is enough, only keep that instance).

2. Basics and Advanced occasionally cannibalise each other's features with little additional content, context, or links provided for further reading

   Consolidate the content (ideally by defining what is considered Basic or Advanced) into a single page for each feature.

[netlify[bot]]

✅ Deploy Preview for gokarna-hugo ready!

Name	Link
🔨 Latest commit	fad063bd79db8039e9e98324a5295efc21e7dddd
🔍 Latest deploy log	https://app.netlify.com/sites/gokarna-hugo/deploys/670d393f621dc800086013f4
😎 Deploy Preview	https://deploy-preview-243--gokarna-hugo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[jamesericdavidson]

@526avijitgupta @yashmehrotra

Should we propose criteria for what should(n't) be considered Basic or Advanced?

2. Basics and Advanced occasionally cannibalise each other's features with little additional content, context, or links provided for further reading

Consolidate the content (ideally by defining what is considered Basic or Advanced) into a single page for each feature.

NACK. Will consider this for a future PR.

[jamesericdavidson]

@yashmehrotra @526avijitgupta

This is my opinionated update to the Basics docs to make it more concise, and suitable for newbies.

I welcome you to read the Summary and preview the changes.

Please note:

• No documentation has been removed, but the text has been streamlined, additional context (in the form of links) has been added, and so on...
• exampleSite's config.toml was updated only to sort the parameters alphabetically (in congruity with the updates made to Basics!)
• exampleSite/public/ was added to .gitignore because it's been driving me crazy for several PRs - this should be a welcome addition for any contributor :wink:

I look forward to your review!

P.S. As mentioned above, only the commits marked docs: are of interest.

[yashmehrotra]

Thanks for the mega update @jamesericdavidson

[yashmehrotra]

Sorry for the delay, will review and merge by weekend

@526avijitgupta Can you have a look too ?

[526avijitgupta]

I'll also review in the next couple of days. Thanks @yashmehrotra @jamesericdavidson

[yashmehrotra]

LGTM

Amazing work @jamesericdavidson

@526avijitgupta can we merge this ?