├── README.md ├── LICENSE └── jade ├── repeating.md └── architecture.md /README.md: -------------------------------------------------------------------------------- 1 | # guidelines 2 | 3 | My thoughts about code authoring 4 | 5 | All guidelines will be grouped by folders. 6 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Даниил Пронин 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /jade/repeating.md: -------------------------------------------------------------------------------- 1 | # Repeating in Pug 2 | 3 | You can do like this: 4 | 5 | ```pug 6 | - 7 | const list = [ 8 | { 9 | title: 'Title 1', 10 | description: 'Description 1', 11 | }, 12 | { 13 | title: 'Title 2', 14 | description: 'Description 2', 15 | }, 16 | { 17 | title: 'Title 3', 18 | description: 'Description 3', 19 | }, 20 | ] 21 | each item in list 22 | .list-item 23 | h3=item.title 24 | p=item.description 25 | ``` 26 | 27 | ```html 28 |
29 |

Title 1

30 |

Description 1

31 |
32 |
33 |

Title 2

34 |

Description 2

35 |
36 |
37 |

Title 3

38 |

Description 3

39 |
40 | ``` 41 | 42 | If you want to vary some item, you have to add another key-value pair into list object: 43 | 44 | ```pug 45 | - 46 | const list = [ 47 | { 48 | title: 'Title 1', 49 | description: 'Description 1', 50 | }, 51 | { 52 | title: 'Title 2', 53 | description: 'Description 2', 54 | selected: true, 55 | }, 56 | { 57 | title: 'Title 3', 58 | description: 'Description 3', 59 | }, 60 | ] 61 | each item in list 62 | .list-item(class=item.selected&&'checked') 63 | h3=item.title 64 | p=item.description 65 | ``` 66 | 67 | ```html 68 |
69 |

Title 1

70 |

Description 1

71 |
72 |
73 |

Title 2

74 |

Description 2

75 |
76 |
77 |

Title 3

78 |

Description 3

79 |
80 | ``` 81 | 82 | Imagine you want to wrap an item into other element instead of add a class. 83 | 84 | Then, use mixins instead: 85 | 86 | ```pug 87 | mixin item(options) 88 | .list-item 89 | h3=options.title 90 | p=options.description 91 | +item({ 92 | title: 'Title 1', 93 | description: 'Description 1', 94 | }) 95 | .wrapper: +item({ 96 | title: 'Title 2', 97 | description: 'Description 2', 98 | }) 99 | +item({ 100 | title: 'Title 3', 101 | description: 'Description 3', 102 | }) 103 | ``` 104 | 105 | ```html 106 |
107 |

Title 1

108 |

Description 1

109 |
110 |
111 |
112 |

Title 2

113 |

Description 2

114 |
115 |
116 |
117 |

Title 3

118 |

Description 3

119 |
120 | ``` 121 | 122 | **Bonus: attributes injecting!** 123 | 124 | You can vary attributes inside one (just one, sorry) of any elements inside mixin using `&attributes` trick: 125 | 126 | ```pug 127 | mixin item(options) 128 | li.list-item 129 | h3&attributes(attributes)=options.title 130 | p=options.description 131 | +item({ 132 | title: 'Title 1', 133 | description: 'Description 1', 134 | })(style='color: red') 135 | ``` 136 | 137 | So, in HTML it will be following: 138 | 139 | ```html 140 |
  • 141 |

    Title 1

    142 |

    Description 1

    143 |
    • 144 | ``` 145 | -------------------------------------------------------------------------------- /jade/architecture.md: -------------------------------------------------------------------------------- 1 | # Jade project structure for static website 2 | 3 | ![](http://i.imgur.com/pBvNagg.png) 4 | 5 | Recently I worked with Jade template engine for creating of some HTML files in addition to Sass to create CSS. Jade is the best template engine I ever seen. 6 | 7 | And one time when my another project was too large and I think that I need a solid project templates structure to simplify next projects maintenance. 8 | 9 | *If you will write an application in Express, you will not ask this question because you already have all this views, partials and other stuff in your framework.* 10 | 11 | So we want to generate a pack of HTML files and upload them to our basic web server (like Github Pages) without any language support like Node, Ruby or even PHP. 12 | 13 | Now I will share my thoughts about Jade project file structure. *Feel free to fix me if you think I’m wrong.* 14 | 15 | ## Files 16 | 17 | Sample project structure: 18 | 19 | - templates 20 | - layouts 21 | - base.jade 22 | - one-column.jade 23 | - two-columns.jade 24 | - components 25 | - header.jade 26 | - sidebar.jade 27 | - slider.jade 28 | - features.jade 29 | - helpers 30 | - profile.jade 31 | - news.jade 32 | - misc.jade 33 | - index.jade 34 | - profile.jade 35 | - archive.jade 36 | - article.jade 37 | 38 | ### `templates` folder 39 | 40 | > Folder that contains all your Jade files because all of they are templates: layouts, components, helpers, files with one mixin inside, etc. 41 | 42 | > Inside this folder you have to put all your Jade files that will directly create HTML files – your **pages**. 43 | 44 | ![](http://i.imgur.com/w0XsmHO.png) 45 | 46 | Every `page` `extends` one of your `layouts` and contains only calls for your `components` or `helpers`, for example: 47 | 48 | `index.jade` 49 | 50 | ```jade 51 | extends layouts/base 52 | block page 53 | +slider(data.content.slides) 54 | +features(data.content.features) 55 | +text(data.content.about.description) 56 | ``` 57 | 58 | > **Note**: There is no any direct HTML into page code. If you will do it you will break all the things I am talking about. 59 | 60 | ### `layouts` folder 61 | 62 | > Every layout there is place where you collect your partials into a wrapper to dance around your main content. 63 | 64 | Every layout extends `base.jade`. 65 | 66 | ![](http://i.imgur.com/DRfoa7l.png) 67 | 68 | Layout can be like this: 69 | 70 | `two-columns.jade` 71 | 72 | ```jade 73 | extends base 74 | block body 75 | +header 76 | block page 77 | +sidebar 78 | +footer 79 | ``` 80 | 81 | > **Note**: You can use some HTML here to wrap your components into wrappers like `.row` or `.small-full.large-8.columns` to follow your CSS framework guidelines, but I am not recommend this. Better to do this with mixin arguments or something smart. 82 | 83 | #### `base.jade` layout 84 | 85 | The place where you can do all smart things and place required HTML tags. 86 | 87 | Example: 88 | 89 | ```jade 90 | block variables 91 | title=data.content.about.name 92 | !doctype html 93 | html 94 | head 95 | meta(charset='utf-8') 96 | title=title 97 | link( 98 | rel='stylesheet' 99 | href='/styles/main.css' 100 | ) 101 | body 102 | block main 103 | script(src='/scripts/main.js') 104 | ``` 105 | 106 | And more, more complicated. 107 | 108 | I used this kinds of magic: 109 | 110 | - multiple variable blocks: for layout settings, for global settings rewriting, for scripts; 111 | - dynamic title based on page ID with flexible separator; 112 | - connecting Bower with `grunt-wiredep`; 113 | - …and compressing them with `grunt-usemin`; 114 | - and much, much more cool things. 115 | 116 | ### `components` folder 117 | 118 | > Every component is a visible part of your project. 119 | 120 | > Components ***must* be reusable**. 121 | 122 | > *It is a very importand part of my idea.* 123 | 124 | > It can be a whole sidebar or part of it, or universal content slider, or limited news loop. 125 | 126 | > But not small parts that is unique for pages or other things. For this we have helpers. 127 | 128 | ![](http://i.imgur.com/h4HmU4D.png) 129 | 130 | A basic component looks like a mixin: 131 | 132 | `news.jade` 133 | 134 | ```jade 135 | mixin news(object, pagination) 136 | each article in object 137 | h3=__(News) 138 | +article-excerpt(article) 139 | if pagination 140 | +pagination 141 | ``` 142 | 143 | It can content any direct HTML generating code like tags or pipes of text (internationalized in my example above). 144 | 145 | ### `helpers` folder 146 | 147 | > Helper is a part of code that you cannot use as a full component but want to store in right place. 148 | 149 | > Helpers ***can* be reusable**. 150 | 151 | It can be a file with all little parts of a page that is unique for it. 152 | 153 | For example, you have Profile page with some components like user badges and avtivity graph. But where you will store unique page header with user avatar, his score and subtitle? 154 | 155 | It is not a component – it can but unlikely will be used somewhere else. It's small. 156 | 157 | It's a small helper that you can store with all other helpers for that page and **quickly rearrange them in your page template**. 158 | 159 | ## Thesaurus 160 | 161 | - **Partial** – a component, helper, mixin or any other part you can use like a solid block. *It is not a functions or other inline things.* 162 | 163 | ## Further reading: 164 | 165 | - [Jade Guidelines](https://github.com/plentiful/guidelines/blob/master/jade.md) by Roman Zolotarev 166 | - [&yet's Code Guide](http://yetiguide.com/#html-syntax) (HTML part is for Jade) 167 | --------------------------------------------------------------------------------