mpetrovich / stylemark Goto Github PK

I believe that the current setup makes it unable to publish the styleguide generated by stylemark directly onto GH-Pages. One thing is adding .nojekyll file because _stylemark has an underscore which conflicts with processing. Another (maybe related) is that html pages refer to the CSS file (actual project code) using absolute refs which translates into

github.com/css/bundle.css

rather than

github.com/{project}/docs/css/bundle.css

Hi,

First of all, great project!

I'm trying to set it up as a very basic example, but unfortunately my custom css is not applied.
The example i've setup is very basic:

/*
---
name: Button
category: Components
---

Buttons can be used with `<a>`, `<button>`, and `<input>` elements.

Types of buttons:
- Default: Standard button

 `` types.html
<button class="btn">Test</button>
 ``
*/
button.btn {
  background: red;
}

(i had to remove one of the three ``` in the code above otherwise it was screwing up the code syntax of github, but in my file they are correct and there are three of them)

The file above is called style.css and it is inside css/

The command i run is: stylemark -i css -o styleguide -b -w

But when i open the browser, here's the result i get:

I don't understand why but my custom style doesn't seem to get applied.

Am i doing something wrong here?

Thanks

OS. Windows 10
Yarn: 1.3.2
NPM: 5.6.0
Node: 8.11.1
Stylemark: 0.6.7

The current mobile menu is implemented by using <select> and <option>, which doesn't work very well. The mobile menu should be the same as the normal left sidebar, by using responsive styling.

If you have a directory structure like
dist
packages/
stylemark.config.yml

and execute command like
stylemark -i packages -o stylemark -c stylemark.config.yml -w 1000 -b 5000

You end up with fs trying to copy to the same directory.
Please see stylemark/src/generator.js:100:9

Would be nice to have documentation coverage reporting to see which components are missing coverage. Something like: https://compodoc.github.io/compodoc-demo-todomvc-angular/coverage.html

h/t @robertSPD

As stylemark is an extension of github flavored markdown, it support the quote element created when using the > character before a line.

Indeed a <blockquote> element is created, but it lacks styling (only has some margin bottom).

It would be nice to add some styling on such element, to make them pop out, a bit like the following:

a blockquote in github

In some projects, I like to have the documentation inside the project (next to the source code), as well as the built output of the documentation (let say you want to publish your doc using Github pages for example, you could build it inside your project).

A project like this is structured like so:

.
├── components/
├── assets/
├── translations/
├── doc/
│   ├── _config.yml/
│   ├── intro.md
│   └── ...
├── build/
│   ├── doc/
│   └── ...
│── package.json
│── webpack.config.js
└── ...

Then I would build or watch the stylemark doc like so:
stylemark -i . -o ./build/doc -c ./doc/_config.yml -w -b

Note that for such projects, the documentation lives inside source code as well as in some dedicated markdown files (and that's why stylemark input is set to .).

But when watching for file changes, the filewatcher sees file changes when stylemark update the content of /build/doc/ — and thus triggering an infinite loop, the doc getting built over and over again.

It would be great to have a proper way to prevent some folders from being watched to prevent such problems.

Hello,

Any idea how a versioning selector could be implemented in Stylemark ?
I was thinking about something like on symfony docs.

Anyway, very good project. Keep up the good work.

I don't believe the search functionality works.

Using the demo at http://stylemark-bootstrap.surge.sh/ I type dropdown into the search box and hit return.

The page reloads with the URL http://stylemark-bootstrap.surge.sh/?filter=dropdown but nothing is different. The full page is loaded and at the top of the page.

Am I missing something?

It would be nice to have an option to allow (default) or dis-allow the HTML accordion from being displayed.

There could be multiple reasons why somebody would like not to show the HTML, for instance, if they are showing off colours; the way I tackled this at the moment is that I've included a class that shows some dots with the background being the colours I want to show, but this HTML markup should really be displayed on the page, as there's nothing helpful there.

Another example could be headings - You want to show the style of the heading but there's no real markup needed in there

I'm trying to add my custom javascript to handle this, but it would be nice to add this feature in my opinion.

Thanks

If you use an external wildcard example, adding an inline or other external example does not work as expected.

For instance, none of these work:

```sample:template.html
```
```sample:files/*
```

```sample.html
<p>Hello, world</p>
```
```sample:files/*
```

where files is a directory containing any number of CSS, JS, or HTML assets.

Hey,

in the description it sais stylemark supports angular but there's no demo code for any Framework

I'd like to generate a living style guide for my angular components - is this possible or is this a "css/less/scss" style guide only?

Altough there's a documentation I think it's lacking a couple of things like code examples for react / angular / ..., what's possible, what's not possible, which angular version is supported (angularJS? angular 2, 4, 5? - does it even matter?)

Thanks in advance!

I'm using a dedicated markdown file in the directory I'm watching to generate the styleguide - but it's not generating the guide. It registers that a change has been made to the file (so I know it's watching the .markdown file) but nothing updates on the front end. The log doesn't show any errors, i.e. in terminal, so I'm not sure if this is a bug or an issue with the markdown file itself...

My code for the file looks like a series of blocks like this:

---
name: Default Table
category: Tables
---

Tables in angular/webapps should only be used for tabular data.

```table-default.html
<table class="table default">
	<thead>
		<th>Table Header</th>
		<th>Header 2</th>
		<th>Actions</th>
	</thead>
	
	<tbody>
		<tr>
			<td>Row 1 cell 1</td>
			<td>Row 1 cell 2</td>
			<td><button>Edit</button></td>
		</tr>
		<tr>
			<td>Row 2 cell 1</td>
			<td>Row 2 cell 2</td>
			<td><button>Edit</button></td>
		</tr>
		<tr>
			<td>Row 3 cell 1</td>
			<td>Row 3 cell 2</td>
			<td><button>Edit</button></td>
		</tr>
	</tbody>
	
</table>```

Hello,

I find that the code blocks are very hard to read, having a very low contrast. It can be quite disturbing especially for documentation with a lot of code examples.

inline code from the Bootstrap example

bigger code block, from a project of mine, even harder to read IMO

I know we can provide our own CSS rules on a per project basis, but I think default style should promote readability and comfort.

How do you feel about it ?

This is a minor issue, but the styling of the select box (when on small screens) is slightly broken. Check the attached screenshot.

Thanks

The stylemark folder starting with an underscore cause problem with github pages.

Files in that folder aren't loaded when you use github pages for you documentation.

Hi,

I've been trying to load the examples inside the comments but the regexp it's unable to locate it. I 've used your sample code inside sass file

/*
---
name: Button
category: Components
---

Buttons can be used with `<a>`, `<button>`, and `<input>` elements.

Types of buttons:
- Default: Standard button
...

The regexp seem's okay on some online validators, so I'm thinking there is some sort of error in the string format.

To illustrate you, the real problem is here:

// Extracts blocks from description
// here description seems a valid string with chosen content
var blocks = description.match(/```(.*\n)+?```/g);
// returns null

Here's my current environment:
OS: Windows 7
Node: 8.5
Yarn: 1.3.2
Stylemark: 0.5.9

It would be useful to control more of the sidebar styling such as logo placement/dimensions, typography, etc.

Unless I'm mistaken, the order property for the stylemark config only allows ordering of categories, and not the named docs in those.

For example, I have a "Coding Guidelines" category, where I want "Overview" to come first, but instead "HTML" is coming before it.

Thanks.

When I run $ npm install --save-dev stylemark or yarn add -D stylemark I get the following:

npm WARN deprecated [email protected]: stop using this version
npm WARN deprecated [email protected]: CoffeeScript on NPM has moved to "coffeescript" (no hyphen)
npm WARN [email protected] requires a peer of stylelint@^8.0.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of stylelint-order@^0.6.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] No repository field.
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

+ [email protected]
updated 1 package in 12.086s

UPDATE: I've since realised this was due to other dependencies needing updates.

I'm seeing behavior when using the -w flag where the browser reloads twice due to the output CSS file being written, then the source map being written. If I disable source map generation, the browser only reloads once. I've tried using the match config option in .stylemark.yml, but I can't seem to get it to work. These are the patterns I've tried:

match: \.css$
match: "\\.css$"
match: css$
match: "css$"

Any idea how I could get this to work? Thanks in advance!

Hi,

It would be good to have an option to use the css (or markdown) order for ordering, rather than having to add + and - in the config file.
This could be especially useful for larger configuration, as the + and - could get quite messy quite quickly.

Thanks

Yarn gives me a warning about stylemark since the latest version.

warning "[email protected]" is missing a bundled dependency "rfr". This should be reported to the package maintainer.

The possibility to hide inline 'files' works just fine, but when trying to hide an external file it doesn't really work properly.
For example this works just fine:

```types.css hidden
body {
  background-color: red;
}```

whereas this does not work:

```types:../lib/style.css hidden```

It justs displays the content of the file in plain text inside the markup, see attached screenshot

I've done some test on running the Stylemark server with npm run start in Windows 10 and Windows 7 and it looks fine in the terminal and the console (except IE which chokes on startsWith), but the iframe won't load in any browser (Chrome, Firefox, IE etc). Everything else seems to be running fine. The entire div.i-example is missing.

I use stylemark version 0.6.1 and I want to use external examples from markdown files.

I have a file that looks like this:

---
name: Links
category: Elemente
---
bla bla bla

``` example:examples/links.html
````

It will generate no example at all. Only when I add an empty inline example block like this:

``` example.html

````

``` example:examples/links.html

````

Then examples/links.html gets rendered. But I have this empty example above the real example. I also noticed in this case that the html box of the example is empty.

I have the following in a markdown file:

---
name: Striped Tables
category: Tables
---
Tables in angular/webapps should **only** be used for tabular data. 

```table-types.html
<table class="striped">
<thead>
	<tr>
		<th>Striped Table Header</th>
		<th>Header 2</th>
		<th>Actions</th>
	</tr>
</thead>

<tbody>
	<tr>
		<td>Row 1 cell 1</td>
		<td>Row 1 cell 2</td>
		<td><button>Edit</button></td>
	</tr>
	<tr>
		<td>Row 2 cell 1</td>
		<td>Row 2 cell 2</td>
		<td><button>Edit</button></td>
	</tr>
	<tr>
		<td>Row 3 cell 1</td>
		<td>Row 3 cell 2</td>
		<td><button>Edit</button></td>
	</tr>
</tbody>

</table>

When it generates the styleguide, the html displays like this:

<table class="table" class="striped">
<thead>
    <tr>
        <th>Striped Table Header</th>
        <th>Header 2</th>
        <th>Actions</th>
    </tr>
</thead>

<tbody>
    <tr>
        <td>Row 1 cell 1</td>
        <td>Row 1 cell 2</td>
        <td><button>Edit</button></td>
    </tr>
    <tr>
        <td>Row 2 cell 1</td>
        <td>Row 2 cell 2</td>
        <td><button>Edit</button></td>
    </tr>
    <tr>
        <td>Row 3 cell 1</td>
        <td>Row 3 cell 2</td>
        <td><button>Edit</button></td>
    </tr>
</tbody>

</table>

It's adding in a class="table" which isn't in the markdown file, and I have no idea why. It only does this with table elements. Any idea why?

Stylemark is asking me for a configuration file, even though the docs claim that -c is optional.

stylemark -i ./sass -o ./sass-documentation -w 2000 -b 8050

Generating style guide...
Missing configuration file

I have an odd behavior in a styleguide I am currently developing due to the iFrameResizer library.

Is there any way to disable some js features through the configuration?

The library defines an option to include external resources (outside MD file):

something:relative.css
or
something:/absolute.css

In either case the style won't get included so the component remains unstyled.
I would opt for being able to include styles from external files because this would enable real modular docs

component1/
   - dist/bundle.css
   - source.scss
   - readme.md
component2/
   - dist/bundle.css
   - source.scss
   - readme.md

Obviously you could include the master style, an outcome of processing all styles but if there are many components with complicated styles you end up having to recompile everything which takes time every time you do a small change in pretty independent component. Normally you would just rebuild the component and load its own bundle.

In GFM tables, pipes can be escaped. However, this doesn't work in Stylemark:

Foo | Bar
--- | ---
`yes \| no` | bar

Expected:

Actual:

I'd love to be able to reference external examples.

I dislike writing ``` all the time and would love to keep my examples in real files, so they are syntax highlighted.

There could be an import directive or a naming scheme to find the files.

#include example/*

Equally named files could be grouped, just as in the markdown.

./example/hello.js
./example/hello.html
./example/hello.jsx

If I run stylemark in watch mode using -w I find that it eventually slows down and becomes unusable. It takes ages to refresh/rebuild and everything starts to lag. Is there something which can be done to improve the performance of the build?

Could we add an option to collapse & expand the generated code the same way we can do with the example code?

h/t @robertSPD

Search on Firefox seems to be broken (62.0b15 (64-bit)).

Searching doesn't do anything:

Console error:

Parser creates <example ...> ... </example> from the code parts in markdown files. If there's height option, the example contains also it. On generator, the example tag is changed to an iframe.

The problem is, if height is not set - iframe has an extra line break, which breaks some browsers.

Prompted by #13

The documentation would be combined into a single doc as if it had always existed in a single file.

Example

example-1.md:

---
name: Example
category: Examples
---
This is the first example.
```example-1.html
<em>Hello, world!</em>
```

example-2.md:

---
name: Example
category: Examples
---
This is the second example.
```example-2.html
<em>Hello, again!</em>
```

This should be handled equivalently to:

---
name: Example
category: Examples
---
This is the first example.
```example-1.html
<em>Hello, world!</em>
```
This is the second example.
```example-2.html
<em>Hello, again!</em>
```

Open questions

1. In what order should files be combined?

• Alphabetically?

2. How should conflicting sets of front matter be handled?

• Use only the first one?
• Merge all, with the first (or last) values taking precedence if there are conflicts?

I'm trying to stand up a direct working example of stylemark (using your predefined examples you used in the bootstrap example), but what i'm getting is the style guide being generated with no "Example" sections, only HTML sections which show the html code, no live examples seem to show at all... here's an example of my yml and my generation configuration:

yml

name: MyProject

assets:
  - styles.bundle.css

sidebar:
  background: "#3b2a55"
  textColor: "#fff"

headHtml: |
  <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">

bodyHtml: |
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
  <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>

node script to run stylemark:

var stylemark = require("stylemark");
var cssFile = "../wwwroot";

stylemark({
    input: cssFile,
    output: '../../docs/styleguide',
    configPath: "./docgenerator.yml"
});

comment structure on compiled css file

    /*
    ---
    name: Button
    category: CSS
    ---

    Button tags
    -----------
    Use the button classes on an `<a>`, `<button>`, or `<input>` element.

    ```tags.html
    <a class="btn btn-default" href="#" role="button">Link</a>
    <button class="btn btn-default" type="submit">Button</button>
    <input class="btn btn-default" type="button" value="Input">
    <input class="btn btn-default" type="submit" value="Submit">
    ```

    <warning>
    #### Context-specific usage
    While button classes can be used on `<a>` and `<button>` elements, only `<button>` elements are 
    supported within our nav and navbar components.
    </warning>
    */

Any help would be appreciated, trying to understand and figure out why everything else seems to work perfectly, it just won't show interactive examples actually render (the iframe and i-example divs)

Hi, I would love to be able to have the ability to specify a custom stylesheet to load after the default Stylemark styles. I love the cleanliness of the default look, but the ability to tweak and extend it to compliment the design of what we are documenting would be a great option for designers.

This could be taken even further with a boolean (include default stylesheet) or another optional field (stylesheet to be used in place of default) that would let us use our own stylesheet to completely style the guide interface.

This approach would keep the lean appeal of Stylemark, as opposed to the bloat of adding custom templates/themes other generators have. I think the ability to use our own styles the default guide markup would add appeal to designers and would let Stylemark users differentiate their docs from other users.

Would love to hear from others' thoughts and ideas on this. Thanks.

Title says it all.

It is a bit unexpected that dirs excluded from being parsed are also watched for re-generation.

Currently, component names must be globally unique.

Example:

in components/usa/button.md:

---
name: Button
category: Components (USA)
---

in components/ger/button.md:

---
name: Button
category: Components (GER)
---

h/t @robertSPD

Please consider adding a documentation to help people setup and explain how to contribute to your project.

I do not believe this exists, if it does I can't find it in the source code or any documentation. Is there currently a way to pass code to head of a component? For example headHtml called out in the YAML block.

If not, I can work on an update

Let me know before I make this update, thanks!

/*
---
name: Button
category: Components
headHtml: <link rel="stylesheet" href="specific-css.css" />
---

Buttons can be used with `<a>`, `<button>`, and `<input>` elements.

Types of buttons:
- Default: Standard button
- Primary: Provides extra visual weight and identifies the primary action in a set of buttons
- Success: Indicates a successful or positive action

```types.html
<button class="btn btn-default">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-success">Success</button>
```
*/
.btn {
    display: inline-block;
    text-align: center;
    vertical-align: middle;
    …
}
.btn-default {
    …
}

It would be great to have a wrapper for each of the example files.
So if you define an example like this;

```example.html
<div class="hello">a</div>
```

and some option like

componentWrapper: "<div class="wrapper">{content}</div>"

you would get

<div class="wrapper">
<div class="hello">a</div>
</div>

in a final example file.

That is very useful for testing - this library works great with backstopjs (you can use example files directly as url in backstop) but if you have a hover shadow it won't get captured. Surrounding div would be great as it could generalize this so you don't even have to encode class selectors anywhere - provide global instead.

Hello!

I was writing a markdown and compiling it with Stylemark normally. However, the page started to translate some code blocks into <code> elements instead of the i-code block. I did some tests and apparently, this bug needs a <h4>Something</h4> followed by an empty line in order to work.

An example:

---base.html
<table>
  <tbody>
    <tr>
      <td class="fs-5 tc">
        <button class="btn">Base Default</button>
      </td>
      <td class="fs-5 tl">.btn</td>
    </tr>
    <tr>
      <td class="fs-5 tc">
        <button class=btn" disabled>Base Default</button>
      </td>
      <td class="fs-5 tl">.btn [disabled]</td>
    </tr>
  </tbody>
</table>
---

<h4>Test</h4>

Test

Obs.: I put '---' just to indicate a code inside .md

This results in breaking some of the code blocks in the page. I tried the same thing with h1, h2, h3, h5 and h6. Apparently, it only works with <h4>

<h4>Test</h4>
Test

This code will not break the page since it doesn't have an empty line being followed by the <h4> line.

To solve this problem, I just used <h3> instead, but I think it is important to report it.

I'm getting this error (variations of it - depending on the code line) while setting up the styleguide:

YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key at line 10

This happens even when I copy-paste the stylemark config example straight from the docs here. Any ideas why?

I've done a process of elimination with the configuration file, it works if I eliminate all config points except the 'name' which is a single line. I looked closely for any tabs or extra/missing spaces that YAML wouldn't accept, and haven't found anything.

Here's my bare-minimum settings file:

name: App Styles

sidebar: 
	background: "#3b2a55"
	textColor: "#fff"

headHtml: 
	<link rel="stylesheet" href="../css/styles.css">

Hi there,

Hope this is the right section - otherwise please point out where to.

I've been trying to set up stylemark in my Angular 4 + Webpack 3 application.
As far as I can see the CLI parses the comments but it doesn't render any custom style.
I believe that's because it is not supposed to compile my *.scss files as well, and indeed there comes my question: how can I load up my stylesheet?
I'm running this npm script (src/styles has a global scss whereas other scss are defined at the component level):
stylemark -i \"src/styles\" -o styleguide -c .stylemark.yml -w 2000 -b 9090

Many Thanks,
Andrea

If one create an anchor link in his doc, to link to another section, this anchor link is being altered by the javascript function that "prefixes all section links with the element name" (app.js l92).

Thus the anchor link doesn't work.