rdwatters / hugo-docs-concept Goto Github PK

Per @bep's comment in forum discussion here:

https://discuss.gohugo.io/t/can-i-check-if-a-shortcode-is-inside-another-shortcode/5811

Standardized author metadata is currently a WIP on the V20 milestones:

gohugoio/hugo#1850

Digitalcraftsman already put together the first round of copy for this feature

See #44 (comment)

Currently, the site navigation is in a site-navigation.html partial and pulls from a sitenavigation.yml data file. In the interest of dogfooding, this partial should be refactored to leverage Hugo's built-in menu system.

For context, the idea behind deviating from menu was that I wanted to make it as easy as possible for creating new content files (esp. functions), and I figured that auto-sorting according to a field in the data file would be easier/faster in future iterations as the site grows.

The YAML examples on this page use the TOML delimiter +++. Instead they should be replaced with ---.

See recent commit on spf13 master:

gohugoio/hugo#3229

I have a subscription to flaticons.com that I used for the homepage icons that I then recolored in Affinity Designer. I liked them...for the first 20 minutes. Now I have my misgivings. Also, since they're more complex and directly embedded as SVGs, they're adding additional HTTP requests and killing the PS scores (not the end of the world).

If anyone can think of some better (svg-based, please) icons...or an image...or whatever...I'm open to it on the homepage.

@budparr @digitalcraftsman @sethmacleod

Cheers.

In order to get Github pages to properly work, you also need to set the baseURL in your project to the starting page for your Github pages repo.

Mirrors @anthonyfok changes per this commit:

gohugoio/hugo@042f8fc

These might live as blog posts in the future. WIP.

See #3

To include

• Twitter
• YCombinator
• Reddit
• "Copy Link" (for easier sharing)

Add Hugo SFTP to tools. See:

gohugoio/hugo@2eb28f8

See related discussion thread here:

https://discuss.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491/16

Commit in spf13/hugo:

gohugoio/hugo@ec3dc32

cc/ @anthonyfok

I used a broken-link checker to find such and it turns out there are quite a few links that cause an 404 error.

This might happen because

• external resources moved/changed/got deleted
  • e.g. from the showcase or articles from the press section
• the edit-this-page button refers to pages that currently don't exist in the spf13/hugo repo
• some tags are linked at the top right on a page that don't exist
  • e.g. the "read more" tag on this page

Here's a list of broken links that cause an 404 error. It's stupid that's not possible to link certain lines in a Markdown file in source code files. Hence I've to guide you differently:

• Link "called directly in the Hugo docs" on [https://hugodocs.info/templates/files/#readfile-example-add-a-project-file-to-content] (at the bottom)

Ryan's added a signature param in the front matter of the function pages. Need to populate those params. The idea is to set the signature to something like this:

apply SEQUENCE FUNCTION [PARAM...]

default DEFAULT INPUT

delimit SEQUENCE DELIMITER [LAST]

dict KEY VALUE [KEY VALUE]...

partialCached PARTIAL [CONTEXT [VARIANT]]

slicestr INPUT START [END]

truncate INPUT LENGTH [ELLIPSIS]

I started looking at this and ran into some issues with multiple functions in the same file (ie. base64.md and math.md). I need to think about how this should be structured.

Inspired by @moorereason 's preferences and Google's documentation:

https://developers.google.com/search/docs/guides/intro-structured-data

In addition to the existing "copy" and "download" buttons in code blocks, users should have the option to toggle between dark and light themes in code blocks. This will likely happen in two parts:

• Add toggle button to all code blocks and create new sass partial for dark theme (likely Monokai for Sublime but with colors tweaked to match Hugo's color palette)
• Leveraging local storage to persist user preference across pages and sessions

The challenge will be appending this toggle to code blocks that are not currently using code shortcode.

I failed to migrate this page over:

http://gohugo.io/tutorials/mathjax/

This can now be incorporated into parts of the supported formats section under content management.

See recent forum thread:

https://discuss.gohugo.io/t/is-there-any-way-to-ignore-underscore-when-rendering-markdown/5801

@budparr

Please see PR here:

#57

@moorereason added signatures field to all files under content/functions and also mentions adding "workson" (see content/functions/format.md). Do you think we can add this to your current single template for the docs theme?

This has moved past deprecation and is no longer supported...

From forums:

https://discuss.gohugo.io/t/site-recent-deprecated-or-removed/5851

This is currently a heading and subheading here:

https://hugodocs.info/getting-started/directory-structure/#homepage-and-list-page-content

However, the _index.md bit is such a common question on the forum, that this should probably only be touched on in the "Directory Structure" page and and then added elsewhere for better discoverability.

Per the following issue and recommendations:

gohugoio/hugo#3143

See related issue on Hugo repo:

gohugoio/hugo#3120

See spf13/hugo issue:

gohugoio/hugo#3246

Per recommendation from @digitalcraftsman here:
gohugoio/hugo#2508 (comment)

Under /tools/migrations, it would be great to have a more step-by-step dissection of the hugo import jekyll command currently in the commands/hugo_import_jekyll/.

This partial is already in the source in layouts/partials/head/metadata-schema-org.html, but this is a partial I used for another project. Need to update to tech documentation for SEO purposes.

All three of the current tutorials are outdated or better explained elsewhere in the documentation. The real question is whether tutorials should live within the Hugo docs site collection in the first place, or if the best approach is to continue pointing users to external resources in "Press and Articles." For example, the Jekyll community has an entirely separate site, and Hexo doesn't have any tutorials at all and neither does Middleman.

This will have multiple steps:

1. The multilingual tutorial is out of date, but the "Customize Dates" section should be incorporated into content-management/multilingual @digitalcraftsman so Golang still doesn't have support for internationalized locale?
2. The "creating a theme" can be removed with parts of it added to /themes/creating/, especially since there are tutorial-specific terms introduced that might confuse users.
3. Migrate from Jekyll can probably be removed entirely but should replaced with either new content for the hugo import jekyll command (difficult to do since everything under /commands is auto-generated or more information added to /developer-tools/migrations/

Blistering Speed
Jettison expensive runtime dependencies, and let Go’s incomparable I/O primitives do the work for you. For the first time, measure build times in micro- and milliseconds.

This may seem like a vanity-issue, but I think you're giving Go too much credit, or, you're giving Go all the credit. It's like saying that it isn't possible to create a fast static site generator in Ruby or Python, which is bullshit. Remember that we doubled the speed in both the 0.17 and 0.18 release, which has very little to do with Go itself.

I suggest a more general "Hugo is blistering fast" without speculating in the why part.

On pages without a previous button, such as https://hugodocs.info/about/ or https://hugodocs.info/getting-started/, the next page button displays on the left side. Presumably it should always be on the right.

It's fixed by changing:

#content-footer {
    justify-content: space-between;
}

to

#content-footer {
    justify-content: flex-end;
}

I know you need space-between for when there are both buttons. I'd submit a PR but I'm not set up for your pipeline.

In order to treat the new docs as a /docs site with the new design for the homepage and news/blog section, the homepage for the docs should take the end user to the first page of the documentation rather than the homepage (i.e., the list page at /about).

cc/ @budparr

See

gohugoio/hugo#3188

Right now, there is a handy math page within the functions section of the site, but this ignores other operators. See this related discuss thread. Possible solutions:

1. Add individual .md for both sets of operators with operators as a tag for a convenient singular view of all three.

2. Create all three sets under a single operators .md within functions, which might make the most sense since extensive basic/advanced examples aren't going to take up a lot of room on the page.

Note(s) to self:

Separate eq that would also need to be consolidated.
The full list of comparison operators is already delimited in where. Probably needs to be reworked for COPE-ishness.

@budparr

This would be easy enough to implement, but I want to open this for discussion first. Bud, I know you are doing considerable leg work right now on the docs theme, so before I add this additional shortcode, I want to make sure it doesn't conflict with your efforts.

Idea:

We currently have "note" and "warning" admonitions. (Here's the docs on restructuredText directives for anyone unfamiliar). Here are the current "semantics":

note: A gentle nudge for the reader to pay closer attention to the content called out. Content includes things like contradictions to other areas of the docs (e.g., if a lookup order were to be different for one template type from another) or maybe minor gotchas.

warning: These are bigger concerns; e.g., breaking changes between versions, hard-to-debug gotchas, common mistakes in themes that cause future breaking changes, etc.

Rationale behind tip:

The idea of a "ProTip" is pretty universal and should probably have it's own admonition in the docs. This is a very common tech doc design component that doesn't really fit into either note or warning.

Why Bring This Up Now?

If we do add this shortcode, I'd like to start implementing across the site before we go live. I can already think of a few places where this type of callout would come in handy.

The Good News:

The templating would be identical to warning or note but with a couple different classes for styling...maybe?

Thoughts?

Per the discussion thread re: code reorganization of functions into namespaces:

https://discuss.gohugo.io/t/plan-for-namespacing-template-funcs/5800/5

This should include typical images for the vendor interface and start with the following assumptions:

1. The user is already comfortable with the CL, git/github.
2. The user has already done the Quick Start or has his/her own completed website that is ready for deployment.

Following suit with the individual function and template pages, the "other variables" page is too encompassing and may prove to be less manageable over time. Need to move git, menu, hugo, sitemap, and shortcode variables into individual .md. Navigation will update accordingly...need to set weight in each of these files as well.

This is already partially improved from the currently published site. See this thread for @bep's suggestion to include minimal visual descriptions for every theme. This is an important accessibility consideration:

https://discuss.gohugo.io/t/theme-recommendations/5816/4

I think the easiest way to take care of this will be to establish some tighter (but not discouraging) editorial/submission guidelines for how theme creators can build a really good README in addition to theme.toml.

Any thoughts, @digitalcraftsman?

See also in main repo:

gohugoio/hugoThemes#226

See related issue on spf13/hugo:

gohugoio/hugo#3249

Feeling that the current homepage is a bit cheesy. I want this to look more like a slick marketing/landing page extolling some of Hugo's features.

This will likely live on a subdomain for review during developer (e.g. https://hp.hugodocs.info).

Some other OS projects with slick landings:

Parse
Feather.js
Yarn
Hyper
Bulma

Just marking this for the moment, but at a glance it seems to me "Quickstart" is still a bit intimidating, particularly if we're linking to it from the home page (which I was thinking about while working on the design, and I think is a good idea).

Perhaps what's there now could be moved to the tutorials section and something a bit less detailed put it in its place. Worth discussing at any rate.

Okay, I just started fooling around with this, mocking up in my browser. Here are some things I did, which are up for discussion.

Primary goal of these changes is to make the documentation more readable.

1. Created a separation between navigation/header and the content below.
   Frankly, the navy blue might be too stark of a contrast, but a good starting place.

2. Made the background color of the body near-white, or a slight gray. This is just meant to create a balance of contrast, because on some screens the white becomes very bright.

3. Put the contextual/page TOC in a box with shadow to clearly separate it from the content it serves. (I felt it blended in too much and created an environment where all one saw was a sea of text).

4. Created a max width for body copy and centered it so it has white space on each side. (it's a basic tenet of setting body copy that it's kept at a reasonable width for reading).

5. Left justified the tags. Keeping it simple here. They distract the eye to the right out of proportion to their place on the page.

6. Added space above headings to better separate one section from another (this isn't apparent from the screenshot).

At any rate, it's just a start to get a discussion going on this.

After running into 2 different errors today, I was thinking about improving the Troubleshooting documentation.

1. Git submodules. Installing a theme with git clone is all well and good, but it should also be added as a submodule.

2. Netlify doesn't always have the most recent Hugo version set as their default version. Currently it is set at 0.17. Netlify allows people to specify more recent versions.

I searched the docs, and I only found a throwaway line about submodules on the Hosting on GitHub tutorial. This seems like the sort of thing that should be explicit in multiple locations: Installing & Using Themes, Relevant Hosting Tutorials, and a Common Errors page. Does that sound reasonable?

If Netlify says it is using the wrong version of Hugo, does it make sense to include that with other common Hugo errors? Or should it just stay in an error section in the Netlify tutorial?

I'll submit a PR updating the docs regarding these errors.

See here.

The following internal templates are not documented in the current or POC site:

_internal/opengraph.html
_internal/schema.html
_internal/twitter_cards.html

Docs for these templates should follow the same model as those used for shortcodes, analytics, and Disqus (i.e., usage sample inputs and outputs for each template).

Also on Discourse forum:

https://discuss.gohugo.io/t/hugo-seo-social-partials/353/41

As seen here: https://hugodocs.info/content-management/front-matter/#front-matter-variables

Note: these are surely issues in the upstream docs, but I don't want us to have to do double work. I'm confident this site will eventually replace the existing docs site.

• There are no required front matter variables anymore. No need to differentiate required/optional variables. Technically, the entire front matter section is optional now.

• The list of page variables is incomplete. See hugolib.Page.update() for the full list of reserved front matter variables.

The order of the tutorials submenu is reversed. I took a look at the site-navigation.html partial, but I can't figure out why Tutorials are behaving differently.

Per recommendation from @moorereason in Hugo forums here:

https://discuss.gohugo.io/t/new-docs-site-need-feedback/5765/7

Should call attention to the following:

• --verbose
• --stepAnalysis
• --renderToMemory
• partialCached function

@digitalcraftsman @moorereason @bep @budparr

1. What's the target build time for building the docs site per @bep 's comment that the docs site is THE representative site for Hugo? (This makes sense for dogfooding.)

Here's on my mid-2012 Macbook Pro, 500gb SSD, 2.6 GHz Intel Core i7, 8 GB 1600 MHz DDR3:

Ryans-MacBook-Pro-2:docs-concept ryanwatters$ hugo --stepAnalysis --renderToMemory
Started building sites ...
Go initialization:
	1.113346949s (1.113802966s)	  251.30 MB 	122794 Allocs
initialize:
	212.547µs (1.114093772s)	    0.17 MB 	278 Allocs
load data:
	21.08919ms (1.135273377s)	    4.41 MB 	139940 Allocs
load i18n:
	200ns (1.135339432s)	    0.00 MB 	0 Allocs
read pages from source:
	113.622354ms (1.249112786s)	   11.29 MB 	109481 Allocs
convert source:
	27.943266ms (1.277214141s)	   19.61 MB 	163911 Allocs
build Site meta:
	2.149305ms (1.279452647s)	    0.33 MB 	12103 Allocs
prepare pages:
	34.191505ms (1.313856577s)	   43.80 MB 	176257 Allocs
render and write aliases:
	5.693574ms (1.319670655s)	    0.90 MB 	16795 Allocs
render and write pages:
	2.889621211s (4.209774815s)	 1952.11 MB 	38189751 Allocs
render and write Sitemap:
	17.709624ms (4.227989034s)	    1.26 MB 	35400 Allocs
render and write robots.txt:
	11.819µs (4.228386929s)	    0.00 MB 	8 Allocs
render and write 404:
	23.416997ms (4.252246753s)	    3.88 MB 	67634 Allocs
Built site for language en:
0 of 7 drafts rendered
0 future content
0 expired content
295 regular pages created
259 other pages created
2 non-page files copied
0 paginator pages created
242 tags created
total in 3138 ms

My typical results running the local server:

0 of 7 drafts rendered
0 future content
0 expired content
295 regular pages created
259 other pages created
2 non-page files copied
0 paginator pages created
242 tags created
total in 3277 ms

And when I switch {{- partial "site-navigation.html" . -}} in baseof.html to {{- partialCached "site-navigation.html" . -}}:

Ryans-MacBook-Pro-2:docs-concept ryanwatters$ hugo --stepAnalysis --renderToMemory
Started building sites ...
Go initialization:
	174.639389ms (175.118835ms)	  251.31 MB 	122831 Allocs
initialize:
	195.392µs (175.403359ms)	    0.17 MB 	278 Allocs
load data:
	18.366801ms (193.893558ms)	    4.41 MB 	139937 Allocs
load i18n:
	241ns (193.974596ms)	    0.00 MB 	0 Allocs
read pages from source:
	21.789181ms (215.906723ms)	   11.41 MB 	109543 Allocs
convert source:
	27.771987ms (243.833173ms)	   19.75 MB 	163959 Allocs
build Site meta:
	2.178849ms (246.099917ms)	    0.32 MB 	12096 Allocs
prepare pages:
	34.853278ms (281.164449ms)	   43.67 MB 	176243 Allocs
render and write aliases:
	6.155326ms (287.483728ms)	    0.90 MB 	16801 Allocs
render and write pages:
	269.83084ms (557.55377ms)	  422.77 MB 	1681913 Allocs
render and write Sitemap:
	13.75197ms (571.515039ms)	    1.26 MB 	35401 Allocs
render and write robots.txt:
	36.122µs (571.749674ms)	    0.00 MB 	8 Allocs
render and write 404:
	1.080643ms (572.98897ms)	    0.55 MB 	1354 Allocs
Built site for language en:
0 of 7 drafts rendered
0 future content
0 expired content
295 regular pages created
259 other pages created
2 non-page files copied
0 paginator pages created
242 tags created
total in 398 ms

I take this to mean that the navigation is the biggest offender, but I'm not sure how to cache/variant this in a way that still gets the desired output w/r/t active classes, etc. I am not using Hugo menus and instead pulling this info from this data file.

Per discussion forum feedback here:

https://discuss.gohugo.io/t/new-docs-site-need-feedback/5765/6?u=rdwatters

See #2864 for a related conversation on a default Hugo theme.

The current Quick Start needs to be scrapped. Here is the first round of very rough, high-level requirements:

• Walk through new "default" Hugo template (Note: need confirmation on whether this feature will ship with v20)
  • Introduces all fundamental concepts: lookup order and directory structure, installing and overriding themes, basic CLI usage, build, custom output formats. These concepts should not be discussed at length but instead point to new sections/content in the docs.
• "Next Steps" page section that includes hosting and deployment options
• Assuming successful installation, the "Quick Start" shouldn't take more than 20-30 minutes (i.e., it should be quick)

In Contrast to Current QS

• Avoid git-related didactics
• Avoid additional scripting, hosting, or deployment instructions

Search icon currently overlaps with the 3-item homepage navigation on mobile...