nodejitsu / docs Goto Github PK

View Code? Open in Web Editor NEW

194.0 194.0 85.0 2.58 MB

Community powered rocket fuel for node.js

Home Page: http://docs.nodejitsu.com

License: Other

JavaScript 64.67% Ruby 0.11% CSS 13.63% HTML 21.59%

docs's People

Contributors

Stargazers

Watchers

Forkers

hamtie david-hosier deanlandolt adammw nodejs-tw fadrizul thejh tarunc gracer-lyl mmalecki ascott max-giro viet-nguyen marcooliveira nvdnkpr krishaamer vicapow jtrick joeybaker jayceefun glowdan soguantenk karlosjota knighthunter09 staxmanade mlippert marcussoliva alex-learn viztor utkars hailiang-wang alainyog annie2010 tiasangtrongdem mahermeg17 lnts2015 keriwarr ifraixedes nelsonic weleoka akatashkov stanisduviy nagendertank jephuff kdemarest neobikes enriqu3jr andrey-pavlov jmjpro paavani alek-s sefigrossman panjiwa10028 balajiace tdurk93 senci eloks cdersky gagarinap simonfan spcolyvas ekelkar m0uneer garlandrileyjr kent10ou minhthong7602 raviiiit nishanthd96 kmwarter radhanathdas ipengr raviatflexiloans mcareunlock mcaresystem prabhatrmishra afreen23 aug2uag glsingh jasonashley sambasivarao93 cuchalin sunitmody milee00me isabella232

docs's Issues

Required Markdown formats & Highlighting

We have been having some problems with the markdown and syntax highlighting. So, I would like to create a new issue where we will be listing everything we need for markdown parsing and syntax highlighting so that we can modify the existing modules if needed.

Markdown Formats

Normal markdown
Code blocks with
```
```language-name

// code in here

```
```

Highlight Syntaxes

Javascript
Ruby
Node REPL

Github flavoured markdown isn't supporting Code blocks.
Highlight.js have many bugs.

Alternate option for Highlight.js

ometa-highlighter
koala (Abandoned)
pygments (Uses pygmentize and is asynchronous)

Articles are not organized consistently

The articles are not organized consistently. The expected organization is Title -> Subtitle -> Article (as described by marak).

Some links on main page get wrapped by anchor tags twice

Example:

<p>Browse /articles/ folder or <a href="http://docs.nodejitsu.com"><a href="http://docs.nodejitsu.com">http://docs.nodejitsu.com</a></a></p>

Not all the links are doing this though, even from the same markdown-parsed source. Maybe it's a bug in the markdown parser?

Add proper <title> for all articles

in /theme/article.html and /generators/article.js

Create view for directory listings

Right now, if you hit a directory without an index.html file, it will use http-server's autoIndex option. This is fine for now, but we should replace this view with a generated listing of the articles.

Remove coffeescript

There shouldn't be any coffeescript in the nodejitsu stack.

<docs> Is that "What is require?" wrong?

I've tested the post "What is require?" and when I'm running it's function 'say' I receive the following error:

example.say()
ReferenceError: message is not defined

Do you know what I did wrong? I'm not understanding it...

Left-menu animation flickering

Currently the sub-menu "drawer" pops out each time you mouse over an element. The animation is very nice, but once the drawer is open, if a user moves to the next top level menu item, the sub-menu text should update (i.e. the animation should not fire again)

Repro

Mouse over "Command Line"
Let drawer slide out
Move mouse to "Child Processes"

Expected: Drawer slide-out animation does fire
Actual: Drawer slide-out animation fires (for a second time).

Background image separating navigation and content missing for iPad's Safari

As discussed in #node.js, the background image separating navigation and content is not showing up on iPad Safari, here's a screenshot:

If I find the fix for this on my bookmarks I'll post a link to it here as well.

Add chartbeat tracking analytics

We should add chartbeat tracking code to the main layout.

Explore the GitHub APIs. Find best node.js GitHub API client.

Add public/ to .gitignore

Miss "authors" data.

Trying to select text in articles causes left-side menu to pop out

Being somewhat new to node.js, naturally I wanted to copy code snippets from the articles on the site. However, once the left-side pop-out menu was added, copying the code snippets became very difficult. As soon as the cursor reaches the first letter on a line, the menu pops out. This only happens on lines that are next to menu items. For example, if a code snippet is below the menu, the described behavior does not occur. I verified this behavior both on Chrome and Firefox 6 on Mac. Love this site though. It already helped me spruce up a couple scripts where I was doing some things incorrectly.

Note that these are not Nodejitsu docs

We should add a footnote somewhere. Users are confusing this article with our official docs and are trying to create an https server on our stack.

Doctypes get stripped by jsdom/weld process

Themes have the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
  ...

but the results look like:

<html>
  <head>

Perhaps this is because the DOM doesn't need doctypes.

This doesn't seem to affect the rendering of our pages, but it would be nice for the purposes of html validation and the like.

Tutorial: Using npm search programmatically

Explicit order for home page left nav

Maybe a dup of #18, but it would be really nice if the left nav in http://docs.nodejitsu.com/ were not sorted alpha but rather sorted in the order that a beginner would walk through docs. For example, Getting Started should be at the top.

[nodedocs.css - personal changes]

I made some simple changes to nodedocs.css in my fork . Perhaps it is worth sharing a couple.

Basically I changed the header, toc > ul, breadcrumbs position to fixed and the header, breadcrumb, breadcrumbs opacity.

header {
opacity: 0.95; /* modfied /
color: #eee;
font-family: 'typewriter';
width: 100%;
position: fixed; / modfied */
top: 0px;
height: 50px;
background-color: #333;
box-shadow: -2px 0px 5px #444;
z-index: 3;
}

toc > ul {

text-transform: capitalize;
background-color: #fff;
padding-top: 20px;
position: fixed; /* modfied */
left: 0px;
min-height: 1000px;
top: 50px;
width: 190px;
box-shadow: 3px -10px 5px #ccc;
webkit-box-shadow: 3px -10px 5px #ccc;
z-index: 2;
}

.breadcrumb {
padding-right: 20px;
font-weight: bold;
font-size: 14px;
background: transparent url('../img/crumbtrail.png') no-repeat scroll center right;
margin-right: 10px;
opacity: 0.2; /* modfied */
}

.breadcrumbs {
position: fixed; /* modfied /
right: -5px;
top: 60px;
padding: 6px;
background-color: #fff;
opacity:0.8; / modfied */
}

/* included */
.breadcrumbs a:hover {
color: black;
opacity: 1;
}

Create Photoshop designs

This should get assigned to Tyrus after the spec and the wireframes have been created.

Wireframes for core UI

Hopefully we can start to flesh this out as a group tomorrow with more of that same exercise. The team will work with @NlCO to draft these to pass off to our new designer.

Tutorial: Beginners guide to using the .pipe() api

article: How to watch a directory for file changes

Add "View all Docs on one page" button

also, we should generate /public/all/index.html with all the articles merged together

Add breadcrumb link to top of every article

Remove all H1 and titles from article.md

There should be no H1s in any of the article.md's. ( # in Markdown )

The title should be represented by the name property in the metadata.json file

::undefined page title

http://docs.nodejitsu.com/

On each "non-article" page you get "::undefined" as a title.

I've cloned the repo, generated the docs and started the server.

2 situations:

visited localhost:8080/ and everything was perfect (clicking on a category opened a sliding submenu)
visited localhost:8080/article and all "category" pages were "::undefined" and also the link "Edit this article" was broken

So I suspect you are routing http://docs.nodejitsu.com/ from localip:port/articles instead of localip:port .. ?

Expose RSS Feed

It would be nice to have an RSS link in the document with a sequential RSS feed of items added to the site.

Checking in generated content.

I do not believe that checking in the generated content is a good idea. I could be wrong. Thoughts?

Proposed Article - How to search files and directories

Article covers how to use native file calls, then suggests using findit instead.

Category and subcategory links should not link to folder listings.

n/t

Unwritten Proposed Articles/Topics

This is a list of proposed topics and articles that haven't been written (about) yet. If you would like to contribute fresh content, feel free to choose one of these articles and flesh it out.

Getting Started

What is node.js?

JavaScript Conventions

What is jslint/jshint?
What is undefined vs null?
EMCA5 functions

Node Conventions

How is the typical application structure? (like bin/, test/, lib/, README as well as github+npm published)
What are middlewares?
How can you do inheritance in node.js?
What is the event loop?

Errors

What does Error X mean? (This should be a table of errors and explanations.)

Fundamentals - Intermediate

How to use Regex in JS (outlined)
How to hash info in node.js?
Testing / How to use the assert module
How to do file uploads?
How do i deamonize my node app? / How to keep my node app running? (forever)
How to use fs.watchFile? (perhaps a lead into the http://github.com/mikeal/watch)
Databases
- How to use Databases in Node.js
- How to interface with:
  - sql (various flavors)
  - couch
  - mongo
  - redis
  - riak
Real-time Webapp
- What are websockets? (socket.io/dnode)
Data Formats
- How to interact with json?
- How to interact with xml?
- How to interact with yaml?
- How to interact with csv?

Fundamentals - Advanced

How to use the DNS module?
How to use the VM module (And Why It's Better Than Eval)
How to use the tty module

Node Must-Have Modules

What is socket.io?
What is async? (or how can I write better async programs?)
What is dnode?
What is connect/express?
What is underscore?
What is coffeescript?

The Node.js Community

What is the "community"?
Using git and Github
The Node.js Mailing list
The IRC and you
search.npmjs.org
Being a good member of the community
Getting help on a project
Contributing back to a project

Consistent capitalization in names and titles

Capitalization in urls, titles and proper nouns should be consistent throughout the docs.

Some guidelines from pull request #44 :

"How To Create a HTTP Request": Capitalized.
"How To Use npm": Lowercased. In my opinion, this should even override title capitalization rules.
/articles/http/clients/how-to-create-a-http-request: Lowercased.

<time> has been deprecated.

I believe the docs "templates" includes some elements, which unfortunately has been deprecated.

Use http://www.whatwg.org/specs/web-apps/current-work/multipage/text-level-semantics.html#the-data-element instead.

Improve breadcrumb section of articles

The styling for the breadcrumbs could be improved. It currently looks like this:

It would be nice if this navigation element was a bit more clearly defined.

Create 404 page

Add `order` property for articles metadata for sorting

We should also then use this value to sort articles when they are generated for views like the table of contents.

Highlight Encoding Problems

I don't know if it's the Markdown module or the template module but there are pages with double encoding (like /advanced/buffers/how-to-use-buffers). I see > all over the place.

missing '}' on the last code example on articles/getting-started/control-flow/how-to-write-asynchronous-code

of this article https://github.com/nodejitsu/docs/blob/master/pages/articles/getting-started/control-flow/how-to-write-asynchronous-code/content.md
on the last code example:
for (var i = 0; i < 5; i++) {
(function(i) {
setTimeout(function () {
console.log(i);
}, i);
})(i);

there should be a '}' on the last line

bad link to error conventions

In this page:

docs/pages/articles/errors/what-is-the-error-object/content.md

There is a link to "article on error conventions" that leads nowhere.

Integrate with Nodejitsu auth for login

All content titles should come from metadata.json, not from path

In a few cases, titles are pulled from path information and not from metadata.json.

Initial page has toc, but no content.

Should have a marketing/blurb or maybe a roadmap or something. some links back to our services and tools.

Can't generate: ENOENT pages/../page.json

I can't generate the docs, using

node bin/docs generate

I get:

GENERATING YOUR FILES
ready to generate docs...
Error: ENOENT, no such file or directory 'pages/../page.json'
    at Object.openSync (fs.js:230:18)
    at Object.readFileSync (fs.js:120:15)
    at sorter (/home/hector/nodejitsu/docs/lib/toc.js:91:16)
    at Array.map (native)
    at Object.sort (/home/hector/nodejitsu/docs/lib/toc.js:67:14)
    at /home/hector/nodejitsu/docs/lib/toc.js:48:15
    at Object.load (/home/hector/nodejitsu/docs/lib/generators/toc.js:21:10)
    at /home/hector/nodejitsu/docs/lib/docs.js:80:47
    at Array.forEach (native)
    at /home/hector/nodejitsu/docs/lib/docs.js:75:24

node v0.6.14
npm 1.1.15

Minor Issues with iOS rendering of site

When on iPad:

`1. The ToC menu can't close.

I thought that the body event would catch this edge case ( see: https://github.com/nodejitsu/docs/blob/master/theme/js/index.js#L42 ) , but it appears to not be working for iOS.

`2. The background image separating navigation and content is not showing up on iPad Safari, here's a screenshot:

var myvalue = first &amp;&amp; second;

The preview of the contend.md is correct though.
https://github.com/nodejitsu/docs/edit/master/pages/articles/javascript-conventions/what-are-truthy-and-falsy-values/content.md

Is this a bug of the syntax highlighter? Extra classes are added to the string &.

Proposed Article - How to access package.json information for npm modules

use https://github.com/indexzero/node-pkginfo