Skip to content

feat: Update preparation section#54

Merged
Owen-sz merged 6 commits into
terrapkg:mainfrom
Daeraxa:update-preparation
Jun 2, 2026
Merged

feat: Update preparation section#54
Owen-sz merged 6 commits into
terrapkg:mainfrom
Daeraxa:update-preparation

Conversation

@Daeraxa
Copy link
Copy Markdown
Contributor

@Daeraxa Daeraxa commented May 29, 2026

As discussed on the Terra Discord.

This PR makes some changes to the the "Preparation" section of the "Getting started" doc. This was created from my own experience of "going in blind" in Terra (and rpm) packaging.

The focus in this section is mostly on some layout changes and adding some additional helping formats into the existing wording rather than attempting to fundamentally change the content.

It does however feature a few changes in the document as a whole as this was necessary to maintain a consistent structure or style.

The below is a list of changes that might not be obvious as to why I changed them, with my justifications for changing them:

  • Added the Tabs and TabItem Starlight component to use as a switcher to reduce the length of the instructions on the page
  • Changed the page title to "Getting Started"
    • This brings it in line with other Terra docs pages and seems to be more accurate - "Contributing" is the category
  • Remove "Overview" Heading.
  • Corrected heading levels, promoting/demoting where necessary. The yaml frontmatter should be the only h1 and the rest are update to logically fit in
  • Converted <code> tags to a code fence format to match the install page and to automatically get the theme decorations. This also makes it easier to contribute as the highlighter takes care of the colours rather than explicitly setting them with ansi codes
  • Converted the mixed list in the container instructions to an unordered list as it wasn't nesting the list items correctly within the new tab switcher.
  • Info strings standardised to sh from shell to match the install page precedent
  • Promoted Linux instructions over Windows or macOS - audience is more likely to be doing this on Linux surely
  • Added type=info attribute to asides if missing (info is default if not specified)
  • A handful of typo/grammar/readability fixes
  • Add the steps component to style specific ordered lists (only for this section but any others will be updated in subsequent PRs).

@GildedRoach
Copy link
Copy Markdown
Member

Some notes before I go into this more in-depth later:

  • Falling back to default on Asides was intended behavior. This is a harmless change, but this was intended.
  • A couple typos I can comment on when I'm not on mobile.

Copy link
Copy Markdown
Member

@Owen-sz Owen-sz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will take a further look later, on a mini vacation right now. Thanks for the contributions!

Comment thread src/content/docs/contributing/getting-started.mdx Outdated
Comment thread src/content/docs/contributing/getting-started.mdx Outdated
Comment thread src/content/docs/contributing/getting-started.mdx Outdated
Comment thread src/content/docs/contributing/getting-started.mdx Outdated
Comment thread src/content/docs/contributing/getting-started.mdx Outdated
@Daeraxa
Copy link
Copy Markdown
Contributor Author

Daeraxa commented May 30, 2026

Addressed most of the feedback.

Whilst looking through the components I did find the Steps component.

I don't want to keep adding new features if this will cause any styling or desired theming issues (as the more theme components you add the less portable the documentation becomes) but the effect of it does looks quite good I think:

image

So if there is a desire, I could add it in. Or do it in a later PR. I think what might be worth it for the documentation as a whole is to make a styleguide or guidelines to make sure that things remain consistent.

@GildedRoach
Copy link
Copy Markdown
Member

Addressed most of the feedback.

Whilst looking through the components I did find the Steps component.

I don't want to keep adding new features if this will cause any styling or desired theming issues (as the more theme components you add the less portable the documentation becomes) but the effect of it does looks quite good I think:

image

So if there is a desire, I could add it in. Or do it in a later PR. I think what might be worth it for the documentation as a whole is to make a styleguide or guidelines to make sure that things remain consistent.

I had actually meant to play with these components but never got to it. IMO this is a perfect fit.

I do plan to make a page dedicated to hacking on these docs, if for no other reason than the README currently holds an entire translation guide that should have its own home. This sounds like a good fit for that.

@Daeraxa
Copy link
Copy Markdown
Contributor Author

Daeraxa commented May 31, 2026

OK, all existing feedback/questions should have been addressed now

@GildedRoach GildedRoach requested a review from Owen-sz May 31, 2026 13:13
@GildedRoach
Copy link
Copy Markdown
Member

After some digging and while we're waiting for Owen, I figured out a less hacky solution for the Badge using HTML.

<div>
  <Badge size="large" text="💙 Thanks for contributing to Terra!" />
</div>

@Owen-sz Owen-sz merged commit 6beeb0b into terrapkg:main Jun 2, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants