This guide will cover how you can customize the look and feel to align it to your specific brand, and how further configuration (like adding a style guide to an existing documentJS docs) can be done.
- -Get using DocumentCSS by following these guides:
- -A quick run through setting up DocumentCSS and generating a simple page.
-An in-depth guide to setting up DocumentCSS with all of the bells and whistles.
-Learn how to create pages, document styles and add interactive demos.
-Align the way the docs look like to your specific brand.
-Make your Living Style Guide available to everybody on your team!
-Once you've created the Living Style Guide, you may want to publish it to share it with your team.
- -However you decide to publish your Living Style Guide, everything you need has been generated in the output directory defined in your document.json configuration file. In our guides, this directory is styleguide. Simply publish this entire folder and you'll have a self-contained site.
Your Living Style Guide will automatically change and evolve along with your project. However, if you'd like your published guide to change as well, you'll need to do some additional setup based on how you're hosting the site.
-If your project is using GitHub Pages, the published version will automatically update whenever you push changes to the gh-pages branch. It is important to note that you must run the documentjs command to build the site locally, then push the generated files to GitHub.
-For other situations, you may need a developer's help with hosting the Living Style Guide. If you need help with a specific project, you can also ask in Gitter.
- -This is a quick run through setting DocumentCSS and generating a simple page. For in-depth instructions, check out the Setup section.
-Install Node.js on your computer and create a package.json file in your project's root directory with something like:
{
- "name": "style-guide",
- "version": "0.0.1",
- "description": "My style guide",
- "author": "",
- "license": ""
-}
-
-From the console or terminal, go to your project folder and use npm to install DocumentJS:
> cd path/to/myproject
-> npm install documentjs
-Create the files and folders that DocumentCSS will use to generate the docs.
-styles which will hold all of your CSS or Less files.styles.md.Your file structure should look like this:
-project
-├──node_modules
-├──package.json
-├──styles
- └──styles.md
-Inside the styles.md add:
@page styles Styles
-
-This is my style guide
-To generate a Living Style Guide, create a file called documentjs.json in the top level of your project.
Your file structure should now look like this:
-project
-├──documentjs.json
-├──node_modules
-├──package.json
-├──styles
- └──styles.md
-Inside of documentjs.json add:
{
- "sites": {
- "styles": {
- "glob": "styles/**/*.{css,less,scss,md}",
- "dest": "styleguide",
- "parent": "styles"
- }
- }
-}
-styles folder and read all files with a css, less, scss or md extension. You can remove either less and/or scss depending on what you're writing styles with.styleguide folder to host the generated HTML pages.styles from styles.md as the main landing page.To generate the Style Guide use open up the terminal and inside of your project's directory run:
-> ./node_modules/.bin/documentjs
-To view the generated site, using terminal navigate to the styleguide directory and use python to start a server:
-> cd styleguide
-> python -m SimpleHTTPServer
-This only applies to Mac or a Linux machines
-Open up a browser and navigate to http://localhost:8000 (if the number above is not 8000, use whatever number you see in your terminal instead). You should see the Living Style Guide with the documentation you just created!
-Your generated Living Style Guide should look like this:
-
Because DocumentJS generates a whole directory based on source files, you'll probably want to mark those files to be ignored by git (or whichever code revision manager you're using).
-If you're using git, create a file named .gitignore at the root of your project (if it doesn't already exist.) Then add the following:
# DocumentJS generated files
- styleguide
-This will mark the whole folder as something to be ignored and your team can avoid merge conflicts on generated files.
-Continue to the next guide:
-> Setting Up DocumentCSS (In-depth Guide).
This is an in-depth guide to setting up DocumentCSS with all of the bells and whistles. For this we will be installing DocumentsJS which powers DocumentCSS.
-First install Node.js on your computer. Then, open the console and navigate to your project. Once in your project, use npm to install DocumentJS:
-> cd path/to/myproject
-> npm install documentjs --save-dev
-The --save-dev flag saves DocumentJS in your package.json so other people who are working on your project can also use DocumentJS.
To generate a Living Style Guide, you only need to configure two things.
-Create a documentjs.json file in the top level of your project like this:
{
- "sites": {
- "styles": {
- "glob": "styles/**/*.{css,less,md}",
- "dest": "styleguide"
- }
- }
-}
-Now let's break down this configuration:
-From documentjs.json:
"styles" : {
-This name can be anything unless you're configuring more than one site, which isn't covered in this guide.
-This is how DocumentJS knows where to look for comments and markdown files that it will used to generate the site. glob specifies a pattern for this.
From documentjs.json:
"glob": "styles/**/*.{css,less,md}",
-This string uses a few different patterns to make sure everything important is included:
-| Context | -Pattern | -Meaning | -
|---|---|---|
styles/**/ |
- /**/ |
- All folders and subfolders of styles should be included |
-
*.{...} |
- * |
- All filenames are included | -
*.{...} |
- {css,less,md} |
- Since {} takes a list, this is shorthand to match all of *.css, *.less, *.md |
-
Altogether, styles/**/*.{css,less,md} means "look in all folders and subfolders of styles for any css, less, or markdown file". If you have additional directories or want to use different file types, this can be adapted accordingly:
"glob": "{styles,static/themes/css}/**/*.{css,scss,md}"
-From documentjs.json:
"dest": "styleguide"
-This is just the name of the folder where your site will be generated. Where you want this to be located will depend on the structure of your project.
-You'll write most of your documentation inline in your css or less files. But you should add one file, styleguide.md, to your styles folder to write your landing page (and set up navigation).
For demos and examples, you may want to create a separate folder to make it easy to link to them later. Make sure not to put anything into the styleguide directory as it is automatically generated.
Your project's directory should will look something like this:
-project
-├──demos
- └──base
- └──forms
- └──demo.html
- └──buttons
- └──demo.html
- └──tables
- └──demo.html
- └──variables
- └──color-palette/
- demo.html
-├──styleguide
- <!-- Automatically generated directory -->
-├──styles
- └──base.less
- └──buttons.less
- └──variables.less
- └──styleguide.md
-Continue to the next guide:
-> Using DocumentCSS.
",n+="",e(this).prepend(n)}),e(function(){var o=function(){var o=e(this).closest("li");e(".sidebar-wrapper").is(".active")&&o.is("ul > li > ul > li")&&e(".scroll-spy-title").click()};e(".contents a").each(function(){return this.href=this.href.replace("#","#section="),e(this).on("click",o),!0});var t=window.location.hash;if(t){var i=t.replace(/.*?#section=/,"#");if(e(i).length){var a=-55;e("html, body").animate({scrollTop:e(i).offset().top+a},500)}}}),window.addEventListener("hashchange",function(o){var t=-55,i=o.newURL.replace(/.*?(#.*)/g,"$1");if(-1!==i.indexOf("#section=")){var a=i.replace(/.*?#section=/,"#"),n=Math.abs(e("body").scrollTop()-(e(a).offset().top+t)),r=Math.max(500,n/6e3*250);e("html, body").animate({scrollTop:e(a).offset().top+t},r)}},!1),e(window).scroll(function(){if(l){var o=document.elementFromPoint(~~(document.body.offsetWidth/2),325);if(o=e(o).closest(".container-fluid > .row > *"),o.length){var t=o.is(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper");t=t?o:o.prevAll(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper").eq(0),!t.length&&e(window).scrollTop()This guide covers how to create, organize and generate a Living Style Guide with DocumentCSS.
- -DocumentCSS uses comments in your stylesheets to generate your style guide documentation. Tags are used in conjunction to add structure to it.
-Prefixed with the @ symbol, tags tell DocumentCSS that there is additional information about the code. For example the tag @description is used to indicate where the description of a style begins.
Use the following tags to structure your Living Style Guide:
-| Tag | -Use To | -
|---|---|
| @page | -Declare a markdown file as a page in your site. | -
| @stylesheet | -Declare a stylesheet file as page in your site. | -
| @style | -Declare a comment as a style inside of a stylesheet. | -
| @demo | -Add an iframe with a demo and html views. | -
| @iframe | -Adds a simple iframe. | -
| @parent | -Specify the parent of a page or stylesheet. | -
| @group | -Specify groups of stylesheets or pages in the sidebar. | -
For additional functionality consult the tags full listing.
-Use this tag inside of a markdown file to represent content that doesn't belong to part of the application structure. Anything that you write below this tag will appear as the description of the page.
-| Arguments | -- |
|---|---|
NAME |
- The unique name of the page. The name is used as a reference for other tags. | -
TITLE |
- The title of the page used for display purposes. | -
Example:
-@page logo-standards Logo Standards
-
-The following guidelines will show your how to use the logo.
-
-With this configuration a page will be created called logo-standards.html. The h1 on the page will be Logo Standards:
Use this tag inside of a stylesheet (CSS, Less, or SCSS) to declare a stylesheet that you want to document in your Living Style Guide. Anything that you write below this tag will appear as the description of the page.
-| Arguments | -- |
|---|---|
NAME |
- The unique name of the stylesheet. The name is used as a reference for other tags. | -
TITLE |
- The title of the page used for display purposes. | -
Example:
-/**
-* @stylesheet buttons.css Buttons
-*
-* There are different button styles that you can use.
-**/
-This will create a page in the styleguide directory called buttons.css.html:
-
Like with the @page tag, anything you write below the tag will be used as a description in the page. Note that because you are adding this content inside of a code file you will need to wrap it in a code comment.
Use this tag inside of a stylesheet that is already using the @stylesheet tag to create a subsection inside of the page and document a set of styles.
| Arguments | -- |
|---|---|
NAME |
- The unique name of the style. The name is used as a reference for other tags. | -
TITLE |
- The title of the style used for display purposes. | -
Example:
-/**
-* @stylesheet buttons.css Buttons
-*
-* There are different button styles that can be used:
-**/
-
-/**
-* @styles buttons-sizes Button Sizes
-*
-* Use button sizes to define the hierarhy between the actions in your page.
-**/
-This will create the section Button Sizes on the page buttons.css.html:
-
Use this tag to add a demonstration of an html file that shows your styles in action. The demo will -render as well an html tab with the markup used for the demo.
-| Arguments | -- |
|---|---|
SRC |
- The source of the html file. | -
HEIGHT |
- The height of the html page. If a height is not provided, the height is determined as the content of the body. | -
Example:
-/**
- * @stylesheet buttons.css Buttons
- *
- * Here's an example of our default button:
- *
- * @demo demos/buttons/demo.html
-**/
-This will show the contents of the demo.html under the Buttons section. The html markup will also be rendered on a separate tab:
-
Use this tag to add a demonstration of and html file without showing the markup used for it.
-| Arguments | -- |
|---|---|
SRC |
- The source of the html file. | -
HEIGHT |
- The height of the html page. If a height is not provided, the height is determined as the content of the body. | -
Example:
-/**
-* @stylesheet buttons.css Buttons
-*
-* Here's an example of our default button:
-*
-* @iframe demos/buttons/demo.html 160
-**/
-This will show the contents of the demo.html right below the section Forms with a height of 160px. The html markup won't be rendered on a separate tab.
-
You can use this tag inside of a markdown file or stylesheet to specify its parent.
-| Arguments | -- |
|---|---|
NAME |
- The unique name of the parent. The name is used as a reference for other tags. | -
ORDER |
- The placement of the children in relation to their siblings. The order starts with 0 and defaults to alphabetical. | -
Example:
-/**
- * @stylesheet buttons.css Buttons
- * @parent styles
- *
- * Here's an example of our default button:
- *
- * @iframe demos/buttons.html
-**/
-
-With this configuration the stylesheet buttons.css will show under the Styles section:
-
You can use this tag to group pages or stylesheets in the sidenav of your Living Style Guide.
-| Arguments | -- |
|---|---|
NAME |
- The unique name of the group. The name is used as a reference for other tags. | -
ORDER |
- The placement of the children in relation to their siblings. The order starts with 0 and defaults to alphabetical. | -
TITLE |
- The title that will be shown in the sidebar. | -
Example:
-@page styles Styles
-@group styles.colors 0 Colors
-@group styles.typography 1 Typography
-@group styles.forms-elements 2 Form Elements
-
-
-This is my style guide.
-
-This will create the groups: Colors, Typography, and Form Elements under the sidebar shown for the Styles section:
-
Now that you have a grasp on what tags are used for, let's dive into how to create your Living Style Guide.
-The first step is to create a page which will be used as the index of your styleguide. To create this page you can create a file in the styles directory called styles.md, and inside add the tag @page. Your code should look something like this:
@page styles Styles
-
-This is my style guide.
-
-Anything after the line with the tag will be used as text on your page.
-With DocumentCSS you can use markdown to semantically structure your documention. Markdown is great becuase is a lightweight markup that won't clutter the comments inside of your style sheets. For example, if you want to call out a piece of text to be displayed as code in markdown you can simply wrap the text in `. For example:
| This Markdown: | -`code` | -
|---|---|
| Will display in the generated HTML as: | -<code>code</code> | -
| Will display on the page as: | -code |
-
Reference this markdown cheatsheet created by gitbub to learn more about how to use markdown in your docs.
-To create links within your documentation simply use the NAME of the page or stylesheet that has been documented using the tags @page or @stylesheet and wrap it in []. For example:
The following page
-@page accesibility Accesibility
-
-Can be hyperlinked like this:
-Referece [accesibility] for more details.
-
-For links external to your style guide, use markdown.
-You can use regular markdown to add images to your style guide.
-To document a stylesheet, open an existing stylesheet or create a new one. You can use .CSS, .Less, or .SCSS extensions. Then, at the top of your document add the @stylesheet tag inside of a css comment. As with the page tag, you can add a description right below it. For example:
-/**
- * @stylesheet buttons.less Buttons
- *
- * Global style definitions for all button elements.
- */
-
-This will create a page called buttons.less.html in the directory that you chose to generate your documentation in.
The next step is to use the @styles tag to organize the styles inside of your stylesheet. For example, inside of your stylesheet for buttons, you may have styles for colors, sizes, and variations. You can use the @styles tag to create sections and document them separately. Besides adding structure to your document, doing this will also allow you to hyperlink directly to that section, as well as to show it on the summary of links at the top of the documentation for that stylesheet.
Here's an example of how this tag can be used:
-/**
- * @stylesheet buttons.less Buttons
- *
- * Global style definitions for all button elements.
- *
- */
-
- /**
- * @styles buttons-sizes Button Sizes 1
- *
- * There are 3 button sizes that can be used:
- */
-
- btn-small {
- ...
- }
-
-
- /**
- * @styles buttons-colors Button Colors 0
- *
- * Use the color variations to denote importance of each action type :
- */
-
- btn-success {
- ...
- }
-
-
-Creating demos allows you to include markup and css in your Living Style Guide to demonstrate your styles in action. For this, create an HTML file inside of your demos directory as it was indicated under the File Organization section.
Inside of this HTML file add the necessary markup and css classes needed for your demo and link your project stylesheet. For example:
-<!DOCTYPE html>
-<html>
-
-<head>
- <meta charset="utf-8" />
- <title>Form Controls</title>
- <link rel="stylesheet"
- href="styles/myproject-min.css" />
-</head>
-
-<body>
- <form>
- ...
- </form>
-<body>
-
-</html>
-
-Then, link this demo to your documentation using the @demo tag:
- /**
- * @styles form-controls Form Controls
- *
- * @demo demos/forms-controls.html
- */
-
- label {
- ...
- }
-
-This will render in your Living Style Guide page as:
- -Note that next to the "demo" tab there is an "HTML". This tab shows any markup inside of your demo, so it's a really nice way of showing your styles in action and how is the markup setup. But if for some reason you don't want to show the markup, you can use instead the tag @iframe which will not render the HTML and the tabs at all. For example:
- /**
- * @styles form-controls Form Controls
- *
- * @iframe demos/forms-controls.html
- */
-
- label {
- ...
- }
-
-Will render in your Living Style Guide page as:
- -Have in mind that before your demos can be visible on your Living Style Guide, you will need to copy them into the directory that you chose to generate your documentation in (styleguide in our example). You can do this by simply copying the demo directory inside of it. To automate this task you can use a task manager like grunt.
---Since your demos and your overall project will be using the same source styles, your live demos will change whenever your design changes.
-
DocumentCSS allows you to organize your documentation independently of how your styles are organized. This is very powerful as you can create a custom information achitecture that better fits your particular needs of presenting your Living Style Guide.
-To create a hierarchy in your documentation your can use the tag @parent. This tag tells DocumentCSS that your @page or @stylesheet has a "parent", and will make it display under that "parent" on the sidebar. For example:
/**
-* @stylesheet checkboxes.css Checkboxes
-* @parent forms 2
-/**
-
-In this example the Checkboxes page will show up in the sidebar under the Forms section in the 3rd position.
-You can also group pages with headings in the sidebar. For this select the parent page where you want to create the group. Then add the tag @group followed by:
-NAME of the group that will be used as reference for other tags,ORDER in which you want your group to show on.TITLE or heading of your group that will be visible on the page.Example:
-@page styles Styles
-@group styles.branding 0 Branding
-@group styles.baseline 1 Baseline Elements
-@group styles.assets 2 Design Assets
-
-This will create the groups: Branding, Baseline Elements, and Design Assets under the sidebar shown for the Styles section.
-While the sidebar is generated via the @parent and @group tags, the top menu on your Living Style Guide is hardcoded in the theme files. To change the navigation menu items, you have to edit the theme file layout.mustache.
There are two ways to do this:
-layout.mustache template file. This is useful if you’re not going to make any other changes to the theme. To do this:
-layout.mustache to a folder called templates in your project (like theme/templates).layout.mustache file.documentjs.json like this:
-"siteDefaults": {
- "templates": "theme/templates",
- },-f flag to force DocumentJS to re-generate the theme files:
- > documentjs -fTo generate your Living Style Guide site open up a terminal in your project's directory and run:
-> ./node_modules/.bin/documentjs
-This will generate your site in the styleguide directory.
If you want an easier way to run this command, first install DocumentJS globally (so it can be run anywhere on your computer):
-> npm install -g documentjs
-Now you can just run this command in any directory with a documentjs.json file:
> documentjs
-Now you just need a way to host your generated site from styleguide. If you're not sure how to do this and are on a Windows computer, you'll need to research it on your own. If you are using a Mac or a Linux machine, use a terminal navigate to the styleguide directory and use python to start a server:
> cd styleguide
-> python -m SimpleHTTPServer
-You should see something like the following:
-Serving HTTP on 0.0.0.0 port 8000 ...
-Open up a browser and navigate to http://localhost:8000 (if the number above is not 8000, use whatever number you see in your terminal instead). You should see any pages that you have created so far!
If you'd like DocumentJS to rebuild the site every time you make changes, you can use the -w (watch) flag while you're working on the site so you don't have to run the documentjs command every time:
> documentjs -w
-Continue to the next guide:
-> Customizing DocumentCSS.
@night/#000000
- @darkSkies/#484848
- @thunderStorm/#706f70
- @cloud/#999999
- @haze/#cccccc
- @fog/#eae9e9
- @clear/#ffffff
- @rain/#1f54c6
- @nightRain/#165489
- @sunrise/#f7f8c3
- @sunset/#d9534f
- Lorem ipsum dolor sit amet, Aenean accumsan diam sed mattis faucibus. Duis in hendrerit urna. Donec egestas libero sapien, quis posuere erat imperdiet id. Morbi erat nulla, feugiat ut lacus vel, placerat ultrices massa. Duis luctus purus vel ligula sagittis laoreet. Nunc sed cursus nibh. Aenean accumsan orci mattis, consequat lorem consequat, vehicula nisi. Nulla iaculis magna sed rhoncus sodales. Aenean pulvinar vitae ante ac lobortis.
- -Sed ultrices suscipit tortor, ac ornare ligula rhoncus ut. Aliquam facilisis suscipit elementum. Integer mattis eu nisi sed aliquam.
- -This is a link
-This text is strong or bold,
-This text is italicized,
-This is super consectetur this is sub
-This has a strike
This is an acronym.
-This text is big
-This text is small
-This is a block quote. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean accumsan diam sed mattis faucibus. Duis in hendrerit urna. -— Placeholder Attribution- -
dfn is the term being defined in this paragraph tag.
- - - - \ No newline at end of file diff --git a/examples/demos/demo.html b/examples/demos/demo.html deleted file mode 100644 index c2bcf41..0000000 --- a/examples/demos/demo.html +++ /dev/null @@ -1,63 +0,0 @@ - - - - - - - - - - - -- Lorem ipsum dolor sit amet, consectetur adipiscing elit. - Maecenas lobortis metus sed risus pretium, at finibus libero bibendum. -
-icon-breakout
- icon-menudown
- icon-bits
- icon-twitter
- icon-canjs
- icon-app
- icon-forum
- icon-chat
- icon-plugin
- icon-code
- icon-article
- icon-muscle
- icon-search
- icon-rocket
- icon-fork
- icon-menuright
- icon-next
- icon-prev
- icon-question
- icon-voteup
- icon-clock
- icon-mug
- icon-shirt
- icon-sticker
- icon-bug
- icon-rss
- icon-user
- icon-github
- icon-award
- icon-close
- icon-check
- icon-google
- icon-Star
- icon-retweet
- icon-reply
- icon-bitovi
- icon-plus
- icon-minus
- icon-logout
- icon-lookright
- icon-lookleft
- icon-flag
- icon-flexible
- icon-photo
- icon-download
- icon-list
- icon-play
- icon-wizard-first
- icon-wizard
- icon-wizard-last
- icon-check
- icon-jmvc
- icon-funcunit
- icon-browsertest
- icon-arrow
- {Code}
- Optional
- Description.
-{Code}
- Optional
- Description.
-{Code}
- Optional
- Description.
-{returns}
- Description.
-- Signature description. Ultrices ante rhoncus lorem fermentum dictum. Quisque - sollicitudin accumsan neque, sed placerat felis placerat at. -
- -
- {small signature code}
-
-
- Description of small signature code above
- -",n+="",e(this).prepend(n)}),e(function(){var o=function(){var o=e(this).closest("li");e(".sidebar-wrapper").is(".active")&&o.is("ul > li > ul > li")&&e(".scroll-spy-title").click()};e(".contents a").each(function(){return this.href=this.href.replace("#","#section="),e(this).on("click",o),!0});var t=window.location.hash;if(t){var i=t.replace(/.*?#section=/,"#");if(e(i).length){var a=-55;e("html, body").animate({scrollTop:e(i).offset().top+a},500)}}}),window.addEventListener("hashchange",function(o){var t=-55,i=o.newURL.replace(/.*?(#.*)/g,"$1");if(-1!==i.indexOf("#section=")){var a=i.replace(/.*?#section=/,"#"),n=Math.abs(e("body").scrollTop()-(e(a).offset().top+t)),r=Math.max(500,n/6e3*250);e("html, body").animate({scrollTop:e(a).offset().top+t},r)}},!1),e(window).scroll(function(){if(l){var o=document.elementFromPoint(~~(document.body.offsetWidth/2),325);if(o=e(o).closest(".container-fluid > .row > *"),o.length){var t=o.is(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper");t=t?o:o.prevAll(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper").eq(0),!t.length&&e(window).scrollTop()| Column Heading | -Column Heading | -Column Heading | -
|---|---|---|
| Content | -Content | -Content | -
| Content | -Content | -Content | -
| - | - | - |
Topics Covered Below:
-The header holds menus for this app, other Bitovi Open-Source products, and other Bitovi related links. At 768px, it collapses to a mobile-style view, putting the main menu under a "Menu" button and removing the menu under the logo altogether.
- - -This dropdown menu shows when hovering the Bitovi bits icon. -Links placed on this menu link out the external Bitovi sites.
- - -This dropdown shows when hovering the logo.
- - -Styles the docs and overwrites some of the theme default styles.
- -Parameters and returns are shown inside of .signature but their styles are not dependant on it.
Used as a wrapper for parameters and returns. The signature has space for headings, code and additional plain-language explanations.
- - -Simple tags are styled independently from parent containers, and are different from the ul.tags li elements.
Styles on base-level tags should live here, including table and form styles. Styles for specific elements or helper classes should go in their separate, respective, files. Typography is housed in its own typography file due to the typical complexity. Global styles, or styles on the body/html should live here.
- -Logo treatments, watermarks etc. to represent the brand.
- - -All defined button styles and states belong here, including any "helper class" button style options, like default, primary etc. DocumentJS only has one defined button, which does not need any additional classes.
The same button styles have been applied to a button class, for use on other html elements emulating a button.
- - -Styles .sidebar-title as a child of the .api list, and up to 5 levels before inheriting the styles of level 1.
Enables both the layout of code wells, and also the syntax highlighting of the specific code language. Syntax coloring provided by prettify.js with the Tomorrow Theme.
-Code "wells" are styled based on the use of the <pre> and <code> tags around your desired code example.
Below are a few examples in various languages. This is not an exhaustive list of supported languages.
-<pre>
- <code>
- <div class="example"><!--with a comment -->
- <h1>Example</h1>
- <p>This is some example code that is being styled.</p>
- </div>
- </code>
- </pre>
-
-var foo = require('f'),
- bar = require('br'),
- writeFile = f.denodify(br.writeFile),
- path = require('path');
-
-module.exports = function(littlePromise, options){
- return littlePromise.then(function(little){
- return writeFile(
- path.join(options.dest,'little.json'),
- JSON.stringify(little) );
- });
-};
-{
- "sites": {
- "docs": {
- "key" : "value"
- }
- }
-}
-Variables used to define the site's color palette.
- -Styles the title section that shows as the top of each document. It is composed by
-a .heading, tags, a subheading, and a list of links.
This dropdown menu shows when hovering the Bitovi bits icon. -Links placed on this menu link out the external Bitovi sites.
- - -This dropdown shows when hovering the logo.
- - -This is the Living Style Guide for DocumentCSS.com. If you'd like to use DocumentCSS to generate your own Living Style Guide, check out our Guides.
- -Layout classes are used to structure the main parts of a page.
- -Styles the title section that shows as the top of each document. It is composed by
-a .heading, tags, a subheading, and a list of links.
Parameters and returns are shown inside of .signature but their styles are not dependant on it.
Styles the groups of lists shown on the sidebar.
- - -Select menu used to display the documentation
- - -Styles the sidebar navigation.
- -Styles .sidebar-title as a child of the .api list, and up to 5 levels before inheriting the styles of level 1.
Styles the groups of lists shown on the sidebar.
- - -Select menu used to display the documentation
- - -Used as a wrapper for parameters and returns. The signature has space for headings, code and additional plain-language explanations.
- - -Simple tags are styled independently from parent containers, and are different from the ul.tags li elements.
",n+="",e(this).prepend(n)}),e(function(){var o=function(){var o=e(this).closest("li");e(".sidebar-wrapper").is(".active")&&o.is("ul > li > ul > li")&&e(".scroll-spy-title").click()};e(".contents a").each(function(){return this.href=this.href.replace("#","#section="),e(this).on("click",o),!0});var t=window.location.hash;if(t){var i=t.replace(/.*?#section=/,"#");if(e(i).length){var a=-55;e("html, body").animate({scrollTop:e(i).offset().top+a},500)}}}),window.addEventListener("hashchange",function(o){var t=-55,i=o.newURL.replace(/.*?(#.*)/g,"$1");if(-1!==i.indexOf("#section=")){var a=i.replace(/.*?#section=/,"#"),n=Math.abs(e("body").scrollTop()-(e(a).offset().top+t)),r=Math.max(500,n/6e3*250);e("html, body").animate({scrollTop:e(a).offset().top+t},r)}},!1),e(window).scroll(function(){if(l){var o=document.elementFromPoint(~~(document.body.offsetWidth/2),325);if(o=e(o).closest(".container-fluid > .row > *"),o.length){var t=o.is(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper");t=t?o:o.prevAll(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper").eq(0),!t.length&&e(window).scrollTop()Variables hold all sorts of site-wide visual configurations. This site has color palettes, logo images, and font declarations set, which are demo'd throughout this live style guide.
- -Variables used to define the site's color palette.
- -Yes! DocumentCSS supports all styling languages (and most development languages, this is a sibling to DocumentJS after all).
-You can read more about how to tell it which languages you're using on the configuration page of the guides.
-DocumentCSS looks for the file types defined in your documentjs.json file. You'll want to edit the "glob" section with file paths and extensions:
{
- "sites": {
- "styles": {
- "glob": "styles/**/*.{less,md}", //<-Looking for LESS and Markdown files in folders inside the styles folder.
- "dest": "styleguide",
- "parent": "styles"
- }
- }
-}You can read more about this on the configuration page of the guides.
-There is! Brandon Reid awesomely put a two-pagestyle guide together for people to play around with. You can find it on Github at: DocumentCSS Starter Kit.
-Here's a high-level overview of the process: You tell documentjs.json to look for your custom template/LESS files, and then these new files need to match the DocumentJS file structure.
The easiest way to go about this is to copy the default DocumentJS theme to your own project and modify it. We also have a few different themes you can use on our Bootdocs project.
-You can get a full breakdown of how to customize your version of DocumentCSS in the customizing look and feel section of the guides. We hope that future versions of DocumentJS will have an easier theming engine.
-Short answer: not easily.
-DocumentCSS is built in LESS and stripping that out in favor of writing styles in another language would be a huge task. With enough time and patience, anything is possible though.
-The top menu is of your Living Style Guide is hardcoded into the theme files. You can learn how to update by following this guide.
-To save time, DocumentJS doesn’t re-build the theme every time the site is generated. In order to get the theme or main navigation to update you have to force the documentjs task. You can do this with the -f flag:
> documentjs -fYou can force and watch at the same time too:
-> documentjs -f -wDepending on the size of your documentation site, this can take a long time. So we recommend dropping the -f unless you're editing the template itself. Documentation comments and demos shouldn't need to be forced.
This is because of one of two issues:
-The path is wrong/there's a typo. Double-check the location of your demo files in relation to the compiled documentation files. If you follow our file structure in the guides, you demos should be accessible by using this path:
-@demo demos/forms.htmlThe demo doesn't exist yet. I pre-link to demos in documentation comments and then forget to actually create the demo all the time.
--It’s important to know that DocumentJS does not move or copy your demos to the generated site folder. Using
-@demoonly tells DocumentJS to create a link to that location. We hope that future versions of DocumentJS will handle this for us.
The demos are highly manual right now and embedded in iframes. What this means is that you'll need to manually link to the compiled stylesheet for your application. You can either use a relative path to the distribution folder your application compiles to, or if your css is hosted online, you can link to that.
-Example: For the demos in our DocumentCSS documentation of Bootstrap elements, Bootdocs, we linked to the Bootstrap CDN so our demos will always reflect any changes Bootstrap makes.
-<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" />
-For the demos on this website, documenting the styles these guides are using, we used a relative path.
-<link rel="stylesheet" href="./static/bundles/static.css" />
-So if you have:
-@demo demos/forms.htmlThen the forms.html file should have a reference to the CSS in the <head> of the HTML. We hope future versions of DocumentJS will automate the inclusion of CSS in demos to make this easier.
If your style guide includes content with the @symbol, like a LESS variable name or media queries, DocumentJS returns a warning because this is the same character it uses to denote relationships and content within the style guide.
So if you see:
- WARNING!!
- There is no @foo tag. did you mean @add ? Simply use two '@'s like so: @@variable-name.
Powered by DocumentJS
-
- 
- DocumentCSS makes it easy to incorporate style documentation as part of your design workflow. Using a combination of custom tags and markdown, DocumentCSS parses coments on your CSS, Less, or SASS and autogenerates a site with your documentation.
- -",n+="",e(this).prepend(n)}),e(function(){var o=function(){var o=e(this).closest("li");e(".sidebar-wrapper").is(".active")&&o.is("ul > li > ul > li")&&e(".scroll-spy-title").click()};e(".contents a").each(function(){return this.href=this.href.replace("#","#section="),e(this).on("click",o),!0});var t=window.location.hash;if(t){var i=t.replace(/.*?#section=/,"#");if(e(i).length){var a=-55;e("html, body").animate({scrollTop:e(i).offset().top+a},500)}}}),window.addEventListener("hashchange",function(o){var t=-55,i=o.newURL.replace(/.*?(#.*)/g,"$1");if(-1!==i.indexOf("#section=")){var a=i.replace(/.*?#section=/,"#"),n=Math.abs(e("body").scrollTop()-(e(a).offset().top+t)),r=Math.max(500,n/6e3*250);e("html, body").animate({scrollTop:e(a).offset().top+t},r)}},!1),e(window).scroll(function(){if(l){var o=document.elementFromPoint(~~(document.body.offsetWidth/2),325);if(o=e(o).closest(".container-fluid > .row > *"),o.length){var t=o.is(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper");t=t?o:o.prevAll(".usability.wrapper, .performance.wrapper, .maintainable.wrapper, .community.wrapper").eq(0),!t.length&&e(window).scrollTop()
Creating a Theme
-To create a theme for your living style guide, first create the following folder structure in the root of your project:
- -
-style-guide-themecan be any name that you want to use for your theme.staticandstylesshould be used for the other folders as this follows the directory structure of the default theme, making it easier to overwrite the styles.The next step is to update
-documentjs.jsonto indicate where the theme resources are located.For example:
- -Overwriting Existing Styles
-To see the default styles, look in: -
-node_modules/documentjs/site/default/static/styles-(you can see these styles documented in Our Living Style Guide).Then copy the file that you want to change over to
-style-guide-theme/static/styles. Inside of this file include only the styles that you want to overwrite and make your changes.Adding New Styles
-If you'd like to add a new LESS file, simply copy over
-styles.less(which imports all the stylesheets) and@importyour new file. DocumentJS will automatically resolve default file imports for any files you don't copy over so don't have to worry about fixing the file paths for the@importstatement.Adding to Existing DocJS
-If your development team is already using DocumentJS to generate JavaScript API docs, you can install DocumentCSS as indicated in this guide having in mind that the configuration of the
- -document.jsonfile will be a little different. Since your project will already contain this file, it will look something like this:To this configuation you will need to add the style guide portion as follows:
- --
Continue to the next guide:
- --> Publishing Your Living Style Guide.