Linking to other components

[pete-hotchkiss]

I could be completely missing this in the documentation, but I can't see where there is a way to have handlebars / MD in a components notes file render a link to another component.

i.e.

This is a description of how this component works. But it's also
similar to {{ components.buttons.cancel-button }}  

Am I just being blind/dumb ?

[allmarkedup]

No not blind or dumb... but because it's actually a theme's job to specify what URLs are available it's a little tricky to provide a way to handle this that still works if people use a different theme from the default.

At the moment I handle this with a custom handlebars helper, and eventually I'll get round to adding some more default helpers in to make stuff like this easier in documentation pages.

For the default theme, the component URLs always take the form of:

• Component detail page: /components/detail/handle
• Component preview page: /components/preview/handle
• Component rendered without preview layout: /components/preview/handle

so you could create a helper that looks something like this:

const Handlebars = require('handlebars'); // note you need to `npm i --save handlebars` first!

function linkTo(handle, view) {
    view = view || 'detail';
    return new Handlebars.SafeString(`/components/${view}/${handle.replace('@','')}`);
}

You obviously still need to register this with the handlebars template adapter but hopefully that will help somewhat?

[mihkeleidast]

Trying to do something similar. A problem arises when generating a static html build of fractal, as all the paths should then have an .html extension. Any simple way to check that?

[isellsoap]

@risker I’m also having the same issue as you. Bummer.

[matt-tyas]

I ended up doing <a href="{% if frctl.env.server %}/components/detail/logo{% else %}/components/detail/logo.html{% endif %}" > It's mucky and it won't work in the markdown though...

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[tlenex]

Trying to do something similar. A problem arises when generating a static html build of fractal, as all the paths should then have an .html extension. Any simple way to check that?

@risker my team uses 2 fractal configuration files, one for dev server and one for dist build. I think you can use similar approach and use different handlebars instances with helpers logic.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[LeBenLeBen]

If that is of any help, I have this Nunjucks helper:

    link(handle) {
      const name = handle.replace('@', '');
      let prefix = '';
      let ext = '';

      if (process.env.NODE_ENV === 'production') {
        prefix = '../..';
        ext = '.html';
      }

      return `<a href="${prefix}/components/detail/${name}${ext}">${handle}</a>`;
    },

Which then allows me to link to other components with: {{ '@handle' | link }}.

Notice that I run my Fractal commands prefixed with NODE_ENV=[development|production] for this to work properly.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[johnstonian]

Trying to do something similar. A problem arises when generating a static html build of fractal, as all the paths should then have an .html extension. Any simple way to check that?

any updates on this? I see the link to https://github.com/frctl/fractal/issues/197 but then I lose track if this particular issue has been solved.

I'd like a way to be able to link to a component in fractal (inside a changelog.md file) that works for both development and static build scenarios.

Thanks for any help!

[mihkeleidast]

Reopening since this is something we should figure out with integrating core/theme/adapter somehow.

I see the need for three usecases:

• linking from component templates (this should be implemented by a helper in adapter)
• linking from docs pages - same as component template
• adding links to context from the config file. sometimes we need to statically link together two view templates, for example, without using helpers in templates, since the url/href should be a simple context value.

[dartanian300]

@mihkeleidast It sounds like this hasn't been solved and there's no workaround in regards to markdown files. Is that correct? We're looking to link many of our components back to one of the documentation pages for reference.

[mihkeleidast]

@dartanian300 the issue is open, so there is no official solution. you can still work around it by creating your own template helper and using that.

[dartanian300]

@mihkeleidast I'm a bit new to Fractal so I could be misunderstanding, but that would only work for components, right? Can I use that in markdown for the notes section?

[mihkeleidast]

Please read the docs: https://fractal.build/guide/documentation/dynamic-docs.html

[dartanian300]

That page should probably be updated to note that the same configuration can be made in the Notes. As is, it appears that you can only do so in the Documentation pages. It's not fully clear for someone new to Fractal.

[mihkeleidast]

It's also documented under the component notes section: https://fractal.build/guide/components/notes.html#the-readme-md-file

If you think the docs can be improved, PRs are welcome.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.