Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add PackageManagerTabs to integration guides #1598

Closed
mrienstra opened this issue Sep 21, 2022 · 4 comments
Closed

Add PackageManagerTabs to integration guides #1598

mrienstra opened this issue Sep 21, 2022 · 4 comments

Comments

@mrienstra
Copy link
Contributor

It would be rad to get PackageManagerTabs into the integration guides.

Example:
https://docs.astro.build/en/guides/integrations-guide/#1-tab.npm
Source:
https://github.com/withastro/docs/blob/e0d8412/src/pages/en/guides/integrations-guide.md?plain=1#L33-L49

The challenge is that the integration guides come from withastro/astro, e.g.:
https://github.com/withastro/astro/blob/ea37de8/packages/integrations/image/README.md

Adding <PackageManagerTabs> to withastro/astro README.md files would result in a broken experience for those viewing the docs via https://github.com/withastro/astro/, so that's a no-go.

Maybe fredkbot could handle this transformation?

Search that matches all 14 occurrences (19 after withastro/astro#4836 lands):

```sh\n# Using NPM\nnpx astro add (.+)\n# Using Yarn\nyarn astro add \1\n# Using PNPM\npnpm astro add \1\n```

We could potentially use Markdown "comments" to mark where this transformation should start & end, though that seems unnecessarily hacky:

<!--- PackageManagerTabs:Start -->
[//]: # (PackageManagerTabs:Start)

For reference, PackageManagerTabs source: https://github.com/withastro/docs/tree/af21fba/src/components/tabs

@mrienstra
Copy link
Contributor Author

Another use case for modifying .md that moves from withastro/astro to withastro/docs:
withastro/astro#4738 (comment)

Starting with a blockquote "note" (see community/community#16925):

> **Note**
> This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.

... Which would render on GitHub as:

Note
This is not supported by the default Squoosh service. See the installation section for details on using the sharp service instead.

... And could then be transformed into:

:::note
This is not supported by the default Squoosh service. See the [installation section](#installing-sharp-optional) for details on using the `sharp` service instead.
:::

... For the Docs site.

@sarah11918
Copy link
Member

Yup, you caught my comment there, and not sure whether you noticed the follow up comment that our plan is in fact to move this content into Docs itself, and out of those READMEs in the following weeks. So this will be easy to do once we've pivoted to that, but is a pain in the butt to think about right now! 😆 (Especially given that we are making a plan so we won't need any workarounds at all.)

@mrienstra
Copy link
Contributor Author

I saw that, I just interpreted "We eventually do want most of this" as "someday maybe hopefully", didn't realize it was a "following weeks" thing! 😅

Will all docs be moving? Or I guess more to the point, integration docs as well? I'm imagining more or less all of the README.md files having a few paragraphs of content at most, with a link leading to the Docs site?

Very very minor downside being not having them at your fingertips when looking through codebase / when working offline, but getting rid of duplication will be a huge win! That and not having to think about rendering differences between GitHub & Docs site anymore.

Anyway, guessing I should close this? Adding PackageManagerTabs to integration guides could become just a simple task on a larger README.md --> Docs site migration checklist, which may already exist somewhere?

@sarah11918
Copy link
Member

sarah11918 commented Sep 22, 2022

It is absolutely on the radar for this quarter, yes. It's in the sprint planning! Trust me, no one more than me wants to extract content out of those README's. 😅

So, I think we are willing to live with the equivalent of what you added to the adapter integration docs (one code snippet showing 3 installation commands) rather than worry about rendering across entirely different platforms.

Closing this issue has the advantage of not making us try to deal with site/UI challenges, but maybe you'll hold us to remembering to turn that one code sample into the tabs that are on several of our other docs pages? 😄

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

No branches or pull requests

2 participants