Extra pages

[nicolas-brousse]

What do you think about having some extra pages like there is in mountain_view gem?

Could be nice to print some info like:

• color palettes, fonts, styleguide details
• some generic information about components

[allmarkedup]

@nicolas-brousse yes that could definitely be a nice addition. Have you any thoughts on how you want to author the content for those pages, or where the content should live in the app? Markdown is probably a good option but is there any other functionality you'd like to see in there?

I've mostly been focusing on Lookbook as a development rather than a documentation tool up until now. But it would be nice if it could be expanded to support more of the docs side of things too, if we can find a nice, intuitive way too add and manage pages like you suggest.

[nicolas-brousse]

@allmarkedup happy that the idea interest you.

Have you any thoughts on how you want to author the content for those pages, or where the content should live in the app?

Since previews path is part of ActionView paths, then maybe the best place could be inside previews folder (ex: test/previews/pages/colors.html.erb).

Markdown is probably a good option but is there any other functionality you'd like to see in there?

If we use normal views, then we let user do what he want.

I've mostly been focusing on Lookbook as a development rather than a documentation tool up until now. But it would be nice if it could be expanded to support more of the docs side of things too, if we can find a nice, intuitive way too add and manage pages like you suggest.

I understand your first approach. I used it recently for my existing components and write previews, and works perfectly 🙂.
I guess it could be useful for teams to share how to use components (notes already help for this) and generic css classes like utilities for example.

I'll explore a bit more and let you know.

[Spone]

This feature would be interesting to publish documentation and previews/examples using the same tool.

I agree with @nicolas-brousse's suggestion of using regular Rails views, so the user can write the pages with their favorite templating language.

Adding a page could be as simple as adding the view (test/previews/pages/colors.html.erb) then visiting /lookbook/pages/colors.

We could also define a convention for the homepage, such as test/previews/pages/index.html.erb that would be rendered when visiting /lookbook.

In terms of navigation, there could be "Pages" item at the top, that would include all existing Pages.

[allmarkedup]

Hey @Spone, yes I agree that this could be a useful feature, and your approach is pretty much what I have been considering,(and what I've done in the past with a previous tool I developed).

There are a few decisions to make with regards to how the pages are actually rendered, with some nuances as to the benefits of each:

1) Render the page in an iframe, using the parent application layout (or an alternative specified via config). The advantage is that there is complete user control over styling, disadvantage is that there are no default styles or highlighting for text content, code samples etc and that it may look a bit odd to have different styling of the pages compared to the rest of the UI.

2) Render the page templates in a Lookbook layout that provides default styles for text content Advantage is that it's really quick and easy to add docs that look good and no whole page iframe is required. But the disadvantages are that it's hard(er) to customise the styling and if rendered components need to be embedded in the docs without styling issues then they need to be rendered in their own embedded iframes, with some javascript to enable the resizing to the height of the component etc.

There is probably some way that both options could be supported, and/or some helpers provided to work around the disadvantages of whichever route was chosen. But there are definitely a few nuances to consider about either approach.

@Spone @nicolas-brousse what would be your preference out of the above options? Or any other suggestions?

[allmarkedup]

Hey guys - I just wanted to update this to let you know that I just released v0.7.0 with support for pages :-)

You can see a few example pages in the demo repo here.

The pages feature is behind an "experimental" flag at the moment so will require feature opt-in as outlined in the docs.

I'd love to get your feedback on it if you get a chance to kick the tyres at any point. There are lots more features that could be added to it but hopefully there is enough there to get you started.

Thanks again for the suggestion - it was actually a fun feature to work on in the end and I think a lot of people might find it useful.

Let me know what you think!

[nicolas-brousse]

@allmarkedup this look really nice! Thank you for this new pretty feature!

For now I only saw one small think missing. It's to be able to update pages layout <head/>, or maybe full layout. For example if I would like to set a color palette from css I build for my app, then I can't use my css classes. Or maybe I miss the info.

[Spone]

Awesome!

Quick question about the docs:

hidden - If false the page will not appear in the navigation but will still be accessible at it's URL (useful for pages that are still in development) [default: true]

Shouldn't the option be named visible if it's true by default, and the false value make the page disappear?

[emilkarl]

@allmarkedup this look really nice! Thank you for this new pretty feature!

For now I only saw one small think missing. It's to be able to update pages layout <head/>, or maybe full layout. For example if I would like to set a color palette from css I build for my app, then I can't use my css classes. Or maybe I miss the info.

Is this possible now in some way? Couldn’t find anything in the docs about it? @nicolas-brousse

[nicolas-brousse]

@emilkarl Yes it is. You may found some documentation here: https://lookbook.build/guide/pages.

[allmarkedup]

@emilkarl actually I'm afraid at the moment there are not really any layout/color palette customisation options for pages. This is something that is on my radar for the future but right now you are pretty much stuck with the default styling I'm afraid :(