hippotastic / astro-docs Goto Github PK

Pathname: /en/core-concepts/partial-hydration/

When using tabs in code blocks, the result currently gets rendered like this:

This looks way too much. We should set the CSS property tab-size: 2 on pre elements to ensure our code blocks look better quickly.

The longer-term solution would be adding automatic linting of Markdown source code to prevent tabs from sneaking into code blocks.

Pathname: /en/core-concepts/partial-hydration/
Issue: {/*<!-- 100% HTML, Zero JavaScript! -->*/}

Code:

---
// Example: Use a static React component on the page, without JavaScript.
import MyReactComponent from '../components/MyReactComponent.jsx';
---
<!-- 100% HTML, Zero JavaScript! -->
<MyReactComponent />

This is a list of things I noticed while reading through our new draft tutorial branch.

• I’d love to be able to look at the finished page I‘m about to build before getting started:

  This is what you‘re about to build: [Link]
  (potentially with a small screenshot)

• The „BY THE END OF THIS SECTION YOU WILL HAVE:“ and the past tense of the bullets feels a bit strange to me. I‘d prefer a „In this step you will (learn how to)“ headline with some present tense bullets

• The Markdown section seems to assume that I know what frontmatter is without stating or explaining it in the introduction.
  The very first code I should insert into the first created file starts like this:

  ---
  title: 'My First Blog Post'
  pubDate: 2022-07-01
  description: 'This is the first post of my new Astro blog.'
  ---
  

  And I‘m maybe really scratching my head at this point what that is and why it‘s even needed. The page calls it „necessary YAML frontmatter“ before and I don‘t know why it‘s even necessary.

  Maybe we could instead start with a Markdown file without frontmatter and then introduce it to solve a problem? Like a URL that‘s being repeated multiple times in the content, moving that up to a frontmatter prop

• I notice that all URLs in the tutorial seem to end without a trailing slash. Isn‘t that opposed to Astro‘s default setting of ending URLs with a slash?

• I may have missed the introduction/explanation for slots, but they suddenly appear when introducing a layout in 4-markdown/2.md. I'd prefer at least a one-liner or inline HTML comment that explains that this is where the content will get rendered.

• It may be useful to link to previous steps of the tutorial in some places if people skip around.
  For example, in the markdown section, we state You already have a BaseLayout.astro for defining the overall layout of your pages. I‘d love to see a link to the relevant section and step around there.

• Testing on Windows has shown that Astro.glob('../pages/posts/*.md') does not guarantee an alphabetical order of the returned array by default. We should therefore not assume in the tutorial that the element at index 0 is going to be the first blog post, but add a one-line sort call to the array or explain how to add it.

Link checker

• Separate build step from linkcheck step
• Change concurrency to prevent unwanted cancelling
• Output annotations where source locations were found first
• Detect incorrect usage of link tags in Markdown pages:

  Extra space [TypeScript] (https://www.typescriptlang.org/).
  

Linter

• Only allow i18nReady in frontmatter of English pages