interactivethings / catalog Goto Github PK

View Code? Open in Web Editor NEW

1.6K 30.0 142.0 18.42 MB

Create living style guides using Markdown or React

Home Page: https://www.catalog.style/

License: BSD 3-Clause "New" or "Revised" License

Makefile 0.10% JavaScript 82.63% HTML 0.31% Shell 0.20% TypeScript 16.63% Nix 0.12%

react catalog styleguide docs documentation style-guide markdown documentation-tool

catalog's People

Contributors

Stargazers

Watchers

Forkers

bebraw neusoft-psd hagerhaf stephenott xiplias ksmalm austinsc enjoylife baletsa z00dev mlipardo hackthings markmurphy craignewkirk mattfelten disintegrator triadai tpreusse avjafrey limerentfox walletcoin tbroadley kyleoliveiro rusinovanton derickwarshaw plaetzchen79 amytych mockingloris picidaejs itslearning ryanberg ellwarco ddanielbee nullnotfound orangecig moklick northwesternmutual trburgess boooya kilian featherart cethy itshizhan chrisdrackett karthik2706 leog davenaeder geraldyeo imcook fc-janharold oohmarty stan-che solublestudio blowery arlandi yyynnn benjazehr o-rango azurementor thiagodemellobueno maxwfreu praneybehl sorosora jagdeepgill krcky moocss clemency10 aliuadepoju einaralex wenjul kristof egdbear petemill trendingtechnology deerandshark qin9smile chrisrivard mersocarlin gdub01 toriaketevan romulocintra iwe7 cartodb idanen unphilosopher newtriks devang-patel alchemy-se yukahighbridge saanch the-cc-dev patrickliu-sa hhy5277 arcluziyang orlandow taechemist hitesh97 pilarargudo papplo tarwn

catalog's Issues

Responsive image specimen

Provide multiple versions of an image. Probably should just use srcset

Clean up dist and built files

The built files shouldn't be committed to the master branch

Always place page navigation at bottom

For pages with not enough content it's placed right after it instead of at the bottom of the viewport.

Allow for project-specific design

Minimize eigenbranding
Icon, logo, or something comparable
Colors

Remove page styles and scripts?

It's not clear to me why we should keep them. If someone wants to add custom CSS and scripts, they should do so in the HTML file.

What do you think @naehrstoff?

Margin-left for lists

List should be indented by a margin on the left side.
This is true for text in specimens as well as outside.

Remove body padding for project specimen iframes

Project specimens' iframes should not contain any padding, the content should go right to the edge of the iframe.

Add arbitrary classes to specimen content

@PiotrF and I were discussing that it'd be useful to add arbitrary classes to specimens. The particular use-case is that we need to simulate a body class each specimen is wrapped in. Currently we can do two things:

<body class="my-body-class"> in the document where Catalog runs. This might break Catalog's own styles though.
Manually wrapping each specimen's code in <div class="my-body-class">...</div>. This seems more "correct" but it's tedious and it adds noise to the specimen's source view.

We've already discussed something similar in #5.

Ideally, we could write:

```html|dark,my-class
…
```

which would output

<div class"cg-Specimen-Html-content cg-Specimen-Html-content--dark my-class">…</div>

The way to decide if this particular class should be namespaced or not would be to check against the defined modifiers (plus run-script).

I don't feel super-excited about this approach. Ultimately I still think, all specimens should be iframed dynamically, so we can encapsulate their styles properly.

Change package name

catalog is already taken on npm.

Fix linting issues

😁

Document Catalog options

Documentation is currently only available by inspecting the example page. The available configuration options should be better documented.

HTML within Markdown does not get parsed correctly

# Example Markdown

This <a href="#">link</a> is not converted correctly.

This &amp; and this &rarr; are not converted correctly.

Decide on one utility library (or none)

Currently we use Ramda, lodash and sprout. We should remove all but one or all of them.

Column layout

It would be nice to have a responsive 3-column layout with arbitrary content

Responsive layout for all screen sizes

Optimize menu for small screens, remove all horizontal padding from cards to test components full-bleed on small screens

Specimen Overview Page

The Specimen Overview page should list all specimens with a short description and a link to the specimen's doc page.

Remove bower.json

Integration with React app

Catalog should be usable in an existing React app to document components

Fit iframes to components

Maybe with https://github.com/davidjbradshaw/iframe-resizer

Also, we should allow defining the size explicitly.

Pass scripts to iframed components

Linking to a Catalog page part

Currently, because we use hash history this isn't possible. We could switch to pushState-style routing but that would require a server which supports that.

Generate several specimens of the same code snippet but with different modifiers

In order to efficiently test various modifiers of a component without duplicating code all the time, it would be nice to be able to specify a list of modifier classes and then generate all variations.

<a class="button">…</a>
<a class="button button--important">…</a>
<a class="button button--large">…</a>
<a class="button button--important button--large">…</a>

The last example shows that it might be interesting to specify a list of lists of modifiers.

Creating React components for this and passing in different properties could be a solution. Those components could then be toString()ed to output “real” HTML. Let's see.

Write documentation for 2.0

Later

Theming

Specimen Documentation

All specimen documentation pages should follow the same structure:

A brief description
Markdown API (options & JSON configuration)
React API (don't worry right now)
Examples with copy-n-pasteable code snippets

Script breaks when `styles` config is not specified

The styles config should be optional.

Upgrade react-router, use plain routes

This will make it easier to integrate in existing React apps

Bring development mode on par with starterkit

Hot reloading and all the rest. Also make should start the server instead of producing a build.

React component specimen

Complete icons specimen

Icons are currently implemented as a specimen, but don't do anything. Finish this.

Rename "Downloadable Content" -> "Download"

Define component configuration options via lang parameter

We need to define which code blocks should be converted to iframes. The only built-in possibility of marked for this is the lang parameter of code blocks.

For example:

```component
<a class="btn">...
```

```component-small
<a class="btn">...
```

Replace code block language overloading with React components

Instead of overloading the code block language parameter with specimen types, change the Markdown renderer to accept React components. With this in place, we can include specimens as JSX React components, clarifying intent and simplifying configuration/extension possibilities.

To help with this endeavor, we might switch to Remarkable as a Markdown renderer. There is the React Remarkable plugin that in theory should support this out of the box:

<Markdown>
  # Catalog example

  > A short introduction

  ## A card

  This card shows a specimen:

  <HtmlSpecimen>
    <button class="button">Button</button>
  </HtmlSpecimen>

  More content follows
</Markdown>

Handle route-not-found

Per-page style injection

Allow user to specify per-page styles that are injected into the page or iframe. This is currently possible for global styles:

Catalog({
  title: "Catalog",
  styles: ["docs/example.css"]
})

Remove stage 0 Babel features

Set .babelrc to "stage": 2 and fix everything until it works again.

Catalog CLI

What about turning Catalog into a CLI tool and/or Node module.

That would have several benefits:

Potential integration of a development server with hot module replacement
No need for index.html
Routes and navigation menu could be auto-generated through directory tree
Wrapping Markdown files into React components could be done by simply concatenating, solving the problem we'd have with #21.
Build to static site = better performance
Catalog on the server = potential integration of an editor

Separate actions (new window, download) and source code tabs
Code block style similar to code specimen
Rename to "Iframe"?