README.md in lookbook-0.6.1 vs README.md in lookbook-0.7.0

- old
+ new

@@ -10,10 +10,16 @@ </div> </div> --- +<div align="center"> +<a href="#installing">Installing</a> • <a href="#previews">Previews</a> • <a href="#pages">Pages</a> • <a href="#config">Configuration</a> +</div> + +--- + **Lookbook gives [ViewComponent](http://viewcomponent.org/)-based projects a _ready-to-go_ development UI for navigating, inspecting and interacting with component previews.** It uses (and extends) the native [ViewComponent preview functionality](https://viewcomponent.org/guide/previews.html), so you don't need to learn a new DSL or create any extra files to get up and running. Lookbook uses [RDoc/Yard-style comment tags](#annotating-preview-files) to extend the capabilities of ViewComponent's previews whilst maintaining compatability with the standard preview class format, so you can add or remove Lookbook at any time without having to rework your code. @@ -27,10 +33,11 @@ - Highlighted preview source code and HTML output - Auto-updating UI when component or preview files are updated _(Rails v6.0+ only)_ - Use comment tag annotations for granular customisation of the preview experience - Fully compatible with standard the ViewComponent preview system - In-browser live-editable preview parameters (similar to basic Storybook Controls/Knobs) +- [**Experimental**] Markdown-powerered documentation pages with embeddable previews ## Lookbook demo If you want to have a quick play with Lookbook, the easiest way is to [give the demo app](https://github.com/allmarkedup/lookbook-demo) a spin. It's a basic Rails/ViewComponent app with a few test components included to tinker with. @@ -71,17 +78,17 @@ 1. Remove the `if Rails.env.development?` condition from around the mount statement in `routes.rb` 2. Add `config.view_component.show_previews = true` to `config/environments/production.rb` -## Usage +<h2 id="previews">Previews</h2> You don't need to do anything special to see your ViewComponent previews and examples in Lookbook - just create them as normal and they'll automatically appear in the Lookbook UI. Preview templates, custom layouts and even bespoke [preview controllers](https://viewcomponent.org/guide/previews.html#configuring-preview-controller) should all work as you would expect. > If you are new to ViewComponent development, checkout the ViewComponent [documentation](https://viewcomponent.org/guide/) on how to get started developing your components and [creating previews](https://viewcomponent.org/guide/previews.html). -## Annotating preview files +### Annotating preview files Lookbook parses [Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) in your preview classes to customise and extend the standard ViewComponent preview experience: ```ruby # @label Basic Button @@ -472,16 +479,222 @@ def default end end ``` -## Configuration +--- -Lookbook will use the ViewComponent [configuration](https://viewcomponent.org/api.html#configuration) for your project to find and render your previews so you generally you won't need to configure anything separately. +<h2 id="pages">🚧 Documentation Pages [experimental]</h2> -However the following Lookbook-specific config options are also available: +If you need to add more long-form documentation to live alongside your component previews you can do so using Lookbook's markdown-powered `pages` system. +> ⚠️ This feature is currently flagged as an **experimental** feature which requires [feature opt-in](#experimental-features) to use. Its API and implementation may change before it is released. +> +> To enable support for pages in your project, add `config.lookbook.experimental_features = [:pages]` into your application configuration file. + +### Pages demo + +For an example of some pages in Lookbook, check out the [example pages](https://lookbook-demo-app.herokuapp.com/lookbook) in the Lookbook demo app and the associated [page files](https://github.com/allmarkedup/lookbook-demo/tree/main/test/components/docs) in the demo repo. + +### Usage + +By default, pages should be placed in the `test/components/docs` directory (although this can be customised) and can be nested in directories as deeply as required. + +Pages must have either a `.html.erb` or a `.md.erb` file extension. All pages are rendered as ERB templates but `.md.erb` files will also additionally be run through a markdown parser. + +Pages can optionally make use of a **YAML frontmatter block** to customise the behaviour and content of the page itself. + +An example page might look like this: + +```markdown +--- +title: An example page +label: Nice example +--- + +This is an example page. If it has a `.md.erb` file extension its +contents will be run through a Markdown parser/renderer before display. + +Fenced code blocks are fully supported and will be highlighted appropriately. + +ERB can be used in here. +The template will be rendered **before** being parsed as Markdown. + +You can can access data about the page using the `@page` variable. +The title of this page is "<%= @page.title %>". +``` + +### YAML Frontmatter + +Pages can use an optional YAML frontmatter block to configure the behaviour of the page and to provide custom data, if required. + +The following page options can be customised via frontmatter: + +* `id` - a custom page ID that can be used for linking to it from other pages +* `label` - The name of the page that will be displayed in the navigation (auto-generated from the file name if not set) +* `title` - The main page title displayed on the page (defaults to the label value if not set). +* `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`] +* `landing` - Set to `true` to use the page as the Lookbook landing page [default: `false`] +* `header` - Set to `false` to hide the page header containing the page title [default: `true`] +* `footer` - Set to `false` to hide the page footer containing the previous/next page links [default: `true`] +* `data` - Optional hash of custom data to make available for use in the page - see info on [page variables](#page-variables) below. [default: `{}`] + +#### Frontmatter defaults + +You can set global default values for page options in the application configuration: + +```ruby +# config/application.rb +config.lookbook.page_options = { + footer: false, + data: { + brand_colors: { + red: #ff0000 + } + } +} +``` + +These will be merged with any page-level frontmatter data. Options set in the frontmatter will override those set at the global level (apart from `data`, which will be deep-merged with the any globally defined data). + +### Page variables + +All pages have the following variables available for use in the page template: + +* `@page` - The current page object +* `@next_page` - The next page object (if available) +* `@previous_page` - The previous page object (if available) +* `@pages` - Collection of all pages + +Page objects have access to frontmatter variables: + +```ruby +The page title is <%= @page.title %> + +Our brand color hex value is <%= @page.data[:brand_colors][:red] %> +``` + +### Ordering pages and directories + +If you want to enforce a specific order for pages and directories in the Lookbook navigation you can prefix the file/directory basename with an 'order number' integer value followed by an underscore or hyphen. + +For example: `01_example_page.md.erb` will be displayed first in the navigation (`01`) within the directory it is in. + +The integer value will be parsed out from the filename so that it doesn't appear in navigation labels or URLs, and the value itself will be used as a 'position' number when sorting the navigation items. + +For example, an ordered directory of pages might look like: + +``` +test/components/docs/ + ├── 01_overview.md.erb + ├── 02_implementation_notes/ + │ ├── 01_slots.md.erb + │ └── 02_html_attributes.md.erb + └── 03_helpful_examples/ + ├── 01_basic_components.md.erb + └── 02_complex_components.md.erb +``` + +Without the number prefixes on the file names the pages may not have appeared in the navigation in the desired order. + +### Linking to other pages + +You can get the path to a page using the `page_path` helper. This accepts a page `id` (as a `Symbol`) or a page object: + +```markdown +Visit the [about page](<%= page_path :about %>) + +Go to the [next page](<%= page_path @next_page %>) +``` + +Page ids can be set in the YAML frontmatter block for that page: + +``` +--- +id: about +--- + +This is the about page. +``` + +### Embedding previews + +You can embed preview examples from your project directly into the documentation pages using the `embed` helper, which renders an iframe with the rendered preview in it at any point in your document. + +The output looks like this: + +<img src=".github/assets/preview_embed.png"> + +To specify which preview example to render, the helper accepts a preview class and a method name (as a symbol), like this: + +```erb +<%= embed Elements:ButtonComponentPreview, :default %> +``` + +#### Preview params + +If you have configured your examples to accept preview params (see the [`@param`](#param-tag) docs), then you can supply values for those params when rendering the embedded preview: + +```erb +<%= embed Elements:ButtonComponentPreview, :default, params: { + icon: "plus", + text: "Add new" +} %> +``` + +### Displaying code + +You can use language-scoped [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) in the markdown file to render nicely highlighted code examples. + +However, if you are not using Markdown, or need a little more control, you can use the `code` helper instead: + +```erb +<%= code do %> + # code goes here +<% end %> +``` + +The default language is `ruby`. To highlight a different language you need to specify it's name as an argument: + +```erb +<%= code :html do %> + <!-- code goes here --> +<% end %> +``` + +> Lookbook uses [Rouge](https://github.com/rouge-ruby/rouge) for syntax highlighting. You can find a [full list of supported languages here](https://github.com/rouge-ruby/rouge/blob/master/docs/Languages.md). + +--- + +### Pages configuration + +These options can be set in your application configuration files to customise the pages behaviour. + +#### `page_paths` + +An array of directories to look for pages in. +Default: `["test/previews/docs"]` + +```ruby +config.lookbook.page_paths = ["path/to/my/pages"] +``` + +#### `page_route` + +The URL segment used to prefix page routes. +Default: `pages` + +```ruby +config.lookbook.page_route = `docs` +``` + +<h2 id="config">General Configuration</h2> + +Lookbook will use the ViewComponent [configuration](https://viewcomponent.org/api.html#configuration) for your project to find and render your previews so you generally you won't need to configure much else separately. + +However the following Lookbook-specific configuration options are also available: + ### UI auto-refresh > ⚠️ UI auto-refresh is only supported in Rails v6.0+ Disable/enable the auto-updating of the Lookbook UI when files change. Enabled by default. @@ -506,11 +719,21 @@ config.lookbook.ui_favicon = "/path/to/my/favicon.png" ``` > To disable the favicon entirely, set the value to `false`. +### Project name +Specify a project name to display in the top left of the UI (instead of the default "Lookbook"): + +```ruby +config.lookbook.project_name = "My Project" +``` + +> If you don't want to display a project name at all, set the value to `false`. + + <h3 id="experimental-features">Experimental features opt-in</h3> Some features may occasionally be released behind a 'experimental' feature flag while they are being tested and refined, to allow people to try them out and provide feedback. > ⚠️ **Please note:** Experimental features should be considered to be **subject to extensive change** and breaking changes to them may be made within point releases - these features are **not** considered to be covered by [semver](https://semver.org/) whilst flagged as 'experimental'. ⚠️ @@ -520,9 +743,14 @@ To opt into individual experimental features, include the name of the feature in the `experimental_features` config option: ```ruby config.lookbook.experimental_features = ["feature_name"] ``` + +The current experimental features that can be opted into are: + +- `pages`: Markdown-powered documentation pages with embeddable previews + #### Opting into all experimental features (not recommended!) If you want to live life on the bleeding-edge you can opt-in to all current **and future** experimental features (usual caveats apply):