animade/frontend-md

Generate simple documentation for your frontend code

Frontend.md

Frontend.md looks at your frontend source code and generates a markdown file (called, predictably, FRONTEND.md) outlining the folder/file structure together with any topline comments. It's not a complete documentation system or styleguide generator. Rather it's designed to be a very simple tool which you can use on new or existing projects to get a high level view of how the code is laid out.

Features

• Portable - drop it into any frontend project and see what's going on
• Easy setup - very little configuration required
• Attractive - generates a nested view of folder structure (inspiration taken from sass-guidelin.es)
• Automated - Parses comments in a file, pulls out the first one and adds it as a description
• Readable - results are saved to a seperate Frontend.md markdown file in the root of your project

Below is a very simple example output for a stylesheets folder. The file descriptions (i.e. "# App Structure" etc) are pulled automatically from the first comment in each file (look in test/source for examples).

source/
|
|- stylesheets/
|  |- app.scss _____________________ # App Structure
|
|  |- modules/
|    |- _footer.scss _______________ # Footer
|    |- _header.scss _______________ # Header
|
|  |- base/
|    |- _base.scss _________________ # Base styles
|    |- _mixins.scss _______________ # Sass Mixins
|    |- _type.scss _________________ # Typography
|    |- _variables.scss ____________ # Variables

Installation

Frontend.md is available via npm, so you'll need node installed. Once that's done, install with:

npm install frontend-md -g

Usage

In the root directory of your project name sure there is a package.json file with the following attributes:

{
  "frontend": {
    "name": "YOUR PROJECT NAME",
    "stylesheets": "RELATIVE/PATH/TO/STYLESHEETS/FOLDER",
    "javascripts": "RELATIVE/PATH/TO/JAVASCRIPTS/FOLDER"
  }
}

Change the values above then generate your FRONTEND.md file by running frontend-md from the root of your project:

frontend-md

All being well, you'll see something like this:

✔ Found package.json...
✔ Found javascripts & stylesheets folders...
✔ FRONTEND.md successfully created :-)

Bugs

This is a very simple project and is held together by bits of string and sticky tape in some places, so if you find bugs please create an issue. Also any contributions or feature suggestions are very gratefully received!

Limitations

Currently compatible with the following file extensions:

• .sass
• .less
• .scss
• .js

Roadmap

• Support for Coffeescript
• Support for Javascript view templates (hamlc etc)
• Add Bower overview

---

Frontend Hound logo is courtesy of Tom Judd.

frontend-md's Issues

So simple and so usefull

Thx

Duplicate use of the parameter name

I think will be nicer if use by default the parameter name existing in package.json. Like:

{
  "name": "Webapp",
  "frontend": {
    "stylesheets": "app/styles",
    "javascripts": "app/scripts"
  },
  [...]
}

Postinstall script fails on Windows

The postinstall command chmod u+x app.js fails on Windows as there's no chmod in Win systems.
There might be a way of executing the command only on *nix based systems?

Make Javascript and Stylesheet entries optional

I really liked the simplicity and would want to use it. But my structure is different.

Currently the below entries are Mandatory in package.json.
"frontend": {
"name": "Flux",
"javascripts": "./src",
"stylesheets": "./"
}
But if your structure is different how do you use it.
I would prefer if along with the name the only thing I can enter is "source": "./src" or similar.
This will pick up my complete structure instead of segregating it by JS and CSS
e.g.
"frontend": {
"name": "Flux",
"source": "./src",
}

chmod in postinstall

Hi.

I did npm install on a windows server, and chmod does not exist there.

Would it be possible to remove chmod for postinstall, or at least make it cross-platform?

Template for FRONTEND.md

If we could change the presentation of FRONTEND.md file would be excellent!

Folder comments?

Hello!

First of all, I absolutely love this tool. So, so useful.

I was wondering whether you'd consider building in support for folder comments? Originally I was thinking you could just have it parse a dotfile in each folder but that would be messy, then I thought it would be easier to just use the package.json?

{
    "frontend": {
    "name": "YOUR PROJECT NAME",
    "stylesheets": "RELATIVE/PATH/TO/STYLESHEETS/FOLDER",
    "javascripts": "RELATIVE/PATH/TO/JAVASCRIPTS/FOLDER",
    "folder_comments": [
            "relative_path_to_folder": "Hello! This is a folder!",
            "assets_scss_vendor_jquery-ui": "jQuery UI styles go here!",
        ]
    }
}

Just an idea! I think it's useful to be able to add comments to certain folders where the developer might be confused about which folder is actually the best place to put a new partial, etc.

Cheers!
Dave

Parse .sass comments

Frontend.md doesn't seem to be parsing .sass comments, which start with //.

I noticed you have something going on here but I lack the competence to debug and eventually fix or implement that myself.

Support for Markdown

Support to read inside scripts and styles folders markdown docs.

Comment parsing

Hi,

It would be really helpful with some config options for the comments parser.

I'd love to use this for my projects but don't fancy changing my team's commenting style for it to work.

Here's an scss example module, whos comment won't be read. (probably due to the first line being blank)

// *************************************
//
//   Example module
//   -> Overview of module and usage
//
// *************************************

// -------------------------------------
//   Base
// -------------------------------------

.module {

    // -------------------------------------
    //   Variables
    // -------------------------------------

    $module-var:    7em;
    $module-col-fg: #3B5998;
    $module-col-bg: #c0deed;


    // -------------------------------------
    //   Elements
    // -------------------------------------


    // ----- Element description ----- // 

    &__element {}


    // -------------------------------------
    //   Variations
    // -------------------------------------


    // ----- Variation description ----- // 

    &--variation {}

}

Less Support

I'd love to add this to our internal styleguide, but we use Less instead of SASS.

I see it's on your roadmap, I just thought I'd add an Issue for visibility and so anyone else can voice any opinions or that they would also like this.

Support for ignore files

We always want to ignore any files that do not want to add in our documentation.