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

docs(storybook): fix broken contribution guide link #569

Closed
wants to merge 6 commits into from

Conversation

cagatay-usta
Copy link

@cagatay-usta cagatay-usta commented May 5, 2023

As the storybook docs import from README.md, the link refers to './CONTRIBUTING.md' which works on github but on Storybook it redirects to 'https://baklava.design/CONTRIBUTING.md' which naturally results in 404.

Only working solution I could come up without creating the need to update both files seperately is to use absolute paths rather than relative, and have both github and storybook links avaliable

Fixes #568

@muratcorlu muratcorlu changed the title docs(storybook): fix broken contribution guide link fixes(#568) docs(storybook): fix broken contribution guide link May 8, 2023
@muratcorlu
Copy link
Contributor

Hi @cagatay-usta. Thanks for the PR.

We use Readme.md as the main welcome content in our repository, and that link works well there. But we also include those md files to our documentation, then problem occurs. Ideally, this link should go to the Contribution guideline in our documentation: https://baklava.design/?path=/docs/documentation-contributing-baklava-contribution-guideline--page But we also have one more environment for our docs for beta versions: https://next.baklava.design I'm not completely sure what is the best way of handling this.

Maybe we should consider preprocessing of those links before publishing our docs. 🤔

@cagatay-usta
Copy link
Author

There is another suboptimal workaround. Keeping github link absolute and storybook link relative,
As storybook MDX docs recommends:
[Go to specific documentation page](?path=/docs/some--id)

For more information please check our [Contribution Guideline document on GitHub](https://github.com/Trendyol/baklava/blob/next/CONTRIBUTING.md), or [on Storybook](?path=/docs/documentation-contributing-baklava-contribution-guideline--documentation).

I tested it locally and both links work on storybook using the above version and it should work on next.baklava.design too, however it's still suboptimal as if one clicks the storybook link on github it wont direct them to storybook page. Still an improvement to current situation though, all links on baklava.design and next.baklava.design will work, and github will still link to github. Only the link to storybook guideline link on github wont work.

I also experimented with options.overrides on markdawn component here welcome.stories.mdx :

import { Meta, Markdown } from '@storybook/blocks';
import ReadMe from '../README.md?raw';

<Meta title="Documentation/Welcome" />

<Markdown>{ReadMe}</Markdown>

but the problem is storybook passes it's own options down to markdown-to-jsx library (I think), as when I try to pass my options to override tags, it messes up with storybook's and codeblocks etc. wont display properly. Someone with more experince may find a way to do it properly so I will link the related docs for the library: https://github.com/probablyup/markdown-to-jsx#optionsoverrides---override-any-html-tags-representation

@erbilnas erbilnas closed this Mar 11, 2024
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.

Contribution Guideline link on Storybook not working
4 participants