semantic-org / learn-semantic

Official repo of learnsemantic.com

Semantic Docs

This folder contains the templates used to generate the static website for learnsemantic.com

How to Use

To install DocPad, the static site generator used to create the html for the site.

npm install -g docpad
docpad install eco;
docpad update; docpad upgrade;

Generating SUI for Docs

Before running server you will need to build your UI files for the docs. Semantic UI includes a special command to build files for a docs instance that must be run from an adjacent Semantic UI folder.

# assumes ./docs and ./ui for default paths, run from ./ui
gulp build-docs

The default location for build-docs is an adjacent folder with the name docs/. The command must be run from your UI folder and not from the docs folder.

To configure a different docs location modify tasks/docs.json

Running Server

You can then start your docs server (and generate docs) using:

docpad run

To watch for changes from your ui folder to serve to your docs instance

gulp serve-docs

Help Fix Typos and Errors

If you find any typos or mistakes, submitting a fix is easy!

Open the documents folder on GitHub, click the edit button on the appropriate page. Then click to submit a pull request.

learn-semantic's Issues

Style Guide

Update style guide to include more information

Language Style Guide

Common Language

These are class names which should be considered when creating a new type variation or content container

Content:

• Action - a list of actions that can be taken by a user
• Content - a group of descriptive elements that require a shared wrapper
• Description - a text element describing another piece of content next to it
• Header - a text header
• Image- an image
• Link - a link element when not specified with an a tag
• Meta - metadata associated with a piece of content
• Text - a single element of text

Variations

• Aligned - 'left aligned', 'center aligned', 'middle aligned', 'top aligned', 'bottom aligned' - element is aligned to have no padding with the element next to it in a direction
• Attached - attached to the top or bottom of other content
• Basic - element has removed all but the most basic formatting
• Colors - red, orange, green, yellow, blue, purple, black, grey, white, brown
• (One, Two Three) - listing the count of elements on a group defines equal width
• Fluid - element takes parent width
• Floating - 'left floating', 'right floating'
• Inverted - colors are inverted for use on dark backgrounds
• (Primary, Secondary) - element changes to be more or less emphasized
• Pointing - element has an arrow pointing to the content it belongs to
• Sizes - tiny, mini, small, medium, large, huge, massive

Types:

• Icon - Element is formatted specifically for an icon with no text
• Labeled Icon - element is formatted for an icon with text alongside it

States:

• Hover - cursor hover
• Focus - element is current mouse target
• Down - touch or mousedown
• Active - currently selected or a module's behavior is activated
• Disabled - cannot be interacted
• Dropped - element has been dropped on
• Dragged - element has been dragged from

CSS

Add examples of each style of comment banner. Ideally would create a snippet/macro for sublime text.

Javascript

Update javascript style guide to include references to the semantic module pattern
http://semantic-ui.com/spec/docs/module.commented.html

Relevance?

Is this still relevant? It hasn't been updated in awhile.

Any unique content aside from http://semantic-ui.com/ should be consolidated. It looks like mostly the "Introduction" and "What's Different" sections.

http://www.learnsemantic.com

The learn semantic ui site (http://www.learnsemantic.com) don't exist as defined in the readme file.

Language dropdown toggles when navigating to different tabs in browser

Click on the language dropdown. Navigate to some other tab in browser. Again click on the http://learnsemantic.com website tab. The state of the language dropdown automatically toggles between close and open.

Mismatched googleFontFamily global site variable

The customizing page shows a snippet of code with a global site variable @googleFontFamily. We are running version 1.12.3 and I can only find these variables as a possible analog:

@importGoogleFonts : true;
@googleFontName    : 'Lato';
@googleFontSizes   : '400,700,400italic,700italic';
@googleSubset      : 'latin';

@googleProtocol    : 'https://';
@googleFontRequest : '@{googleFontName}:@{googleFontSizes}&subset=@{googleSubset}';

Not sure if I am mixing concerns here or if there is a conflict.

Add edit link to the bottom of every Learn Semantic article

This idea is very much inspired by what npm did with docs.npmjs.com – we should add a dynamically generated "edit this article" link to the bottom of every article on Learn Semantic. This would drastically lower the barrier of entry for people contributing to these articles – instead of having to shift context away to GitHub to hunt for the article they were just reading on Learn Semantic, they can go straight to editing it.

See https://docs.npmjs.com/getting-started/what-is-npm for example:

Take a look at this template and this script to see how they did it.