Break: Migrate to Hugo

[lukeed]

Foreword: This PR represents the WDC team's ongoing work to migrate the entire dev docs website to Hugo, a popular static-site generator. In doing so, all of the content has been relocated (and in some cases, updated). Because of this, all code owners are automatically being notified & requested for a review.

A few weeks ago, @codewithkristian sent out an internal email to all teams alerting you all of this upcoming change and the rollout schedule. Please take some time before this Friday (Feb 25) to review the changes and the deployed site (see Pages live demo) for any issues or inconsistencies. Sorry for the pings, but appreciate your feedback, review, and time! 🙇

High-level Changes for Content Contributors & PCX

• The /products/ top-level directory has been renamed to /content/ – required by Hugo

• Each markdown file (*.md) needs to have a title: defined in its frontmatter. This was previously optional, but is now required (by Hugo) as this frontmatter-defined title determines how the page is displayed in all sidebars, tables, and content lists. The title within the page (eg, # Hello World) is the page's content and may be different than the title: frontmatter value.

• The order frontmatter key has been renamed to weight. It still affects list sorting/ordering.

• A weight of 0 signifies that the item/page should not appear in a sorted list. This is equivalent an empty order: in the previous engine. Previously, an order: 0 meant that the item would be first, but that should now be weight: 1

  # Before
  order: 0 # ~> first
  order: 1 # ~> second
  order:    # hide me
  
  # After
  weight: 1 # ~> first
  weight: 2 # second
  weight: 0 # hide me

• (New) There's now a meta block that can be defined within a page's frontmatter. It has the title and description keys, each of which can be optionally defined to custom the pages' relevant meta tags for SEO purposes. Changing a meta.title, for example, does not change the page's content title nor its title when displayed in the sidebar, lists, and tables.

  For example, the following page will have a meta title of "Hello Crawlers", a "Hello Lists" for sidebars/etc, and read "Hello World" in the actual page content:

  ---
  title: Hello Lists
  meta:
    title: Hello Crawlers
  ---
  
  # Hello World
  
  This is my page

• Hugo does not accept JSX/MDX anymore. Instead, markdown content needs to use Hugo shortcodes. Nearly all the previous components have an equivalent shortcode. The shortcode syntax is as follows:

  <!-- shortcode without arguments or inner content -->
  {{<shortcode>}}
  
  <!-- shortcode with arguments -->
  {{<shortcode foo="bar" hello="how are you?">}}
  
  <!-- shortcode with arguments and inner content -->
  {{<shortcode foo="bar" hello="how are you?">}}
    Can contain markdown, or other shortcodes! [Go to Home](https://cloudflare.com)
  {{</shortcode>}}

  Our most common "shortcode" (previously "component"), was the Aside. Here are some before/after examples:

  <!-- Before -->
  <Aside type="note" header="Hello World">
  
    It **needed** to have newline buffers before **and** after the inner content.
    Otherwise, it would always be a build-time error that could be hard to find.
  
  </Aside>
  
  <!-- After -->
  {{<Aside type="note" header="Hello World">}}
    Now newlines **are not required** and you can still use markdown!
  {{</Aside>}}
  
  {{<Aside>}}
  
    But you can add/keep them if you want :)
  
  {{</Aside>}}
  
  {{<Aside type="note">}}This is also valid... if you want!{{</Aside>}}

• There's also a special {{<render file="...">}} shortcode. This is a way to inject reusable markdown partials into a page. This feature was already in use with the old engine, but now takes a new form:

  <!-- Before -->
  
  import TutorialsBeforeYouStart from '../../_partials/_tutorials-before-you-start.md'
  
  # Hello World
  
  <TutorialsBeforeYouStart/>
  
  <!-- After -->
  
  # Hello World
  
  {{<render file="_tutorials-before-you-start.md">}}

  The way this works is that every product section (eg, content/workers vs content/pages) can have its own _partials subdirectory. When you use the render partial, its file argument references a filepath from the current product's _partials directory. This allows you to safely construct paths to partials from anywhere deep within the file tree.

  You will notice that the files within the _partials directory have some funky-looking frontmatter. This is just a way to prevent Hugo from rendering the _partials/** as standalone HTML pages.

• (Important) Constructing links to other pages is now more intuitive and aligned with expectations. Every link must be an absolute path, starting with the product's name. This also means that you can cross-link to other products without requiring the full https://developers.cloudflare.com/... prefix to escape the link-rewriting that took place.

  <!-- file: content/workers/demo.md -->
  
  <!-- before -->
  [Workers Tutorials](/tutorials)
  [Pages Tutorials](https://developers.cloudflare.com/pages/tutorials)
  
  <!-- After -->
  [Workers Tutorials](/workers/tutorials)
  [Pages Tutorials](/pages/tutorials)

(Local) Development

With this move to Hugo, the entire dev docs are built and deployed as a single application!

This means that you build and develop the entire website easily – not just 1/47th of the website at once. This also makes it easier to ensure that cross-content links to other pages actually work :)

Instructions for getting started locally are included in the updated README.md file, but the cliff notes are:

1. Install Hugo – at least 0.92.x is required
2. Install Node.js – at least 14.x is required but 16.x is recommended
3. Run npm install (or equivalent, thru another package manager)

Local Development

You can run npm run dev (or equivalent; eg yarn dev) to start a live-reload development server on http://localhost:1313. Any changes you make to the repository should instantly recompile & automatically reload any browser tabs open to the localhost address.

Note During development, syntax highlighting will not be colorized. This is expected (and temporary 🤞)

Production Build

You can run npm run build (or equivalent; eg yarn build) to build the project for production. A public top-level directory will be created, containing all the minified assets. This is the directory that Pages will deploy.

Note: Production builds will have colorized syntax highlighting.

Building for production will run a few extra scripts that don't run during development. This includes:

• npm run format – which formats all markdown files (including code blocks) for consistent code style
• npm run highlight – which will apply the previous engine's syntax highlighting rules to the code snippets

---

Please do reach out with any questions or concerns.

We will be freezing / limiting other PR merges until Friday so that the deploy preview (here) remains up-to-date with the latest content.

Thanks! 🙇 👋

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Pages

Latest commit:	ce64f4d
Status:	✅  Deploy successful!
Preview URL:	https://3907b79b.cloudflare-docs-7ou.pages.dev

View logs

[williamhorning]

Hey there, I saw this pull request linked in the Cloudflare Developers Discord server. It's really cool to see how much of a difference moving to Hugo makes. I noticed that it looks almost the same, except for the sidebar.
On https://migrate.cloudflare-docs-7ou.pages.dev/api/ the scrollbars are shown, while the currently deployed version has no scrollbars on that same page.
In addition, the scroll bars aren't styled on this version. On https://migrate.cloudflare-docs-7ou.pages.dev/logs/ the scrollbars aren't styled while the scrollbars on the currently deployed version are styled.

[eidam]

👏 👏 👏 👏 👏 👏 👏 👏