Jss: Create a landing page with better documentation

[kof]

Would appreciate any help in design or docs.

[typical000]

Created a simple example of starting screen https://dl.dropboxusercontent.com/u/7605560/jss/design.jpg
Here:

• Left menu is fixed
• Central logo will move with mouse like here

Soon, when I have more free time, I'll add design of next sections :)

[kof]

nice!!!

[typical000]

Created full and more detailed design template witch demonstrates first 2 sections and something like brandbook, or... base styles of main elements (paragraphs, headings, lists, inputs, buttons, tables):

Default:
https://dl.dropboxusercontent.com/u/7605560/jss/design_full.jpg
With open single menu item (from previous picture, where menu items have arrow icon):
https://dl.dropboxusercontent.com/u/7605560/jss/design_full_menu.jpg

Also, when I have time I'll take Jekyll that is supported by github out of the box and create some static template...

[kof]

What if we use react and jss?)))

[kof]

We can use also ssr + rehydration ....

[typical000]

We can use also ssr + rehydration ....

But we can't use ssr if we use gh-pages... :(

[kof]

we can generate the html, see react-ssr example https://github.com/jsstyles/examples/tree/gh-pages/react-ssr

[kof]

@typical000 can you attach here the source files of your design?

[typical000]

Sure!
PSD: https://dl.dropboxusercontent.com/u/7605560/jss/design.psd
JPG examples:
https://dl.dropboxusercontent.com/u/7605560/jss/design_full.jpg
https://dl.dropboxusercontent.com/u/7605560/jss/design_full_menu.jpg

Some weeks ago I have just started to do something with this design, but, unfortunately, now I have some problems with working with opensource, and what is done is like 5% of all :(
The main idea was to create something like 'site-constructor' where with one json you can configure all menu with pairs "Name + URL" (Url will be *.md files from main repo with JSS documentation) and all content will be loaded by something like markdown-loader...

[typical000]

During some tries to implement something good and having short exprerience with css-modules I have faced problem that i miss class composition. So I'll switch to #265 and try to imlement plugin first

[kof]

You aren't implementing jss landing page with css-modules, are you?

[typical000]

No-no. With jss. I just realized that I am missing jss-compose to be happy)

[kof]

I think we need to create a landing page in order to render a composed documentation view from all plugins.

[kof]

Nobody will go through every plugin page and read that documentation.

[kof]

Also we are currently hiding the entire power of jss + plugins by not having one place where the entire thing is documented.

[typical000]

@kof You are right. My idea was to create json file for navigation like

{
  "Home": "some-url-to-readme.md",
  "Functions": "some-other-url.md",
  "Plugins" {
     "jss-extend" : "url-to-extend-jss.md",
     "jss-default-unit" : "url-to-bla-bla.md"
  }
  ...
}

And when app bootstraps left menu goes filled by this structure. On changing page - MD files will be loaded by ajax and using with some webpack markdown loader.

What is done:

1. Left menu - logo, menu populating by json, github widget that fetch stars using github api
2. Promo block with floating JSS logo

Todo:

1. Internal pages layout and styling
2. Loading markdown
3. Responsive
4. Webpack. Now my webpack solution is a piece of shit used from side project that is dead :) Need to make something small that just compile (Why I haven't changed webpack before - because I was concentrated in styling and content :)).
5. SSR. Looks like something went wrong. Need to return to this. Now I'm sending from server base styles. Other is rendered on frontend. Maybe for this small landing page we can build all on server and don't care about all.
6. Maybe update dependencies for jss and all plugins

[kof]

I think its easier to get the md files locally when all plugins are installed.

[typical000]

Main idea was to use the same MD files that are used inside jss and jss plugins repo. So we don't need to change in 2 places them if we add new features :)

[kof]

That should be definitely the case, we can't duplicate them.

[typical000]

@kof I have just created in those days repo for our landing page. You can view here:
https://github.com/typical000/jss-landing
and see published example here:
https://typical000.github.io/jss-landing

Short info about

1. Build entirely with react, jss, and react-jss
2. All pages structure is generated by simple config https://github.com/typical000/jss-landing/blob/master/src/pages.json . In few words - every page content is loaded dynamically from other repos in MD format (so we don't need to prepare some separated and extra content), converted in HTML and inserted inside. Short walkthrought about pages.json:
   
   
   
   1. home - indicates that is homepage. So when we go to / url app redirects to this page. And parallax scene with big logo will be rendered
   
   
   2. external - indicates that page is external resource and it must be opened in new window (see pages "Live Examples" and "Playground")
   
   
   3. child - insert child sub-pages
   
   
   4. name - if you don't set this property - page will be inside application router structure, but no left menu link will be generated (in case if you need some... hidden pages :D)
   
   
3. All loaded content goes processed
   
   
   
   1. All code is higlighted by prism.js
   
   
   2. All links changed
      
      
      
      
      
      1. If links sends us to some page that is inside internal structure (https://github.com/typical000/jss-landing/blob/master/src/pages.json) - we change URL to fit inner router
      
      
      
      2. If link starts with # - add "scroll to" animation on click
      
      
      
      3. If link sends us outside to external resource - add target="_blank"
      
      
      
   
   
4. Main repository stars in left sidebar are fetched from github. So, it will be actual forever
5. Site is responsive! :)
6. Site have 404 page :D Don't know why - but if you go on non-existant route you recieve something like this

What we need to do now

1. Create gh-pages for JSS repository and move here this site
2. Go through all JSS repos *.md filex and fix:
   
   
   
   1. Transform urls like href="./performance.md" to absolute path. Because landing can't handle such links and sends us to 404 page.
   
   
   2. Fix internal anchors in docs. For e.g. https://raw.githubusercontent.com/cssinjs/jss/master/docs/js-api.md - first 3 links are not working.
   
   
   3. Change headings to right ones (e.g. on some pages there are a lot of H2, like here)
   
   
   4. Remove from plugin pages JSS logo. Is inutile widget. We know that is JSS :) and on landing it looks a little strange
   
   
3. Do something with examples section. I suggest to add separately styles inside examples repo to make examples look similar to current site. Because now they looks like form 20 century :D

So, if you are ok I can do this work in nearest weeks. :)
Maybe any other suggestions.

[kof]

Wow, you did a huge work over there!

Create gh-pages for JSS repository and move here this site

I think a separate repository "landing" is better

Transform urls like href="./performance.md" to absolute path.

I think its easier and better to fix such links after downloading the md file. Its easy to do with markdown-it parser.

Fix internal anchors in docs. For e.g.

Is already fixed in the branch I am working on and will be released very soon.

Change headings to right ones (e.g. on some pages there are a lot of H2, like here)

agreed

Remove from plugin pages JSS logo.

agreed

Do something with examples section.

Maybe we should render them inside of an iframe?

[kof]

cc @okonet

[kof]

Some feedback:

• navigation scrolling doesn't feels right, I would make the entire sidebar scrollbar
• logo text position is a bit different in the original design
• what is this white arrow in the navigation on the "JSS Plugins" menu?
• I would recommend this markdown parser, its the best
• We can use jss-preset-default and jss-isolate, also use jss-expand where possible (f.e. boxShadow), use jss-extend instead of spread operator
• Publish normalize as a separate package!

[typical000]

I think a separate repository "landing" is better

Hm... If we put it in separated repo url will be https://cssinjs.github.io/landing it's ok? Or are you planing to buy unique domain like jss.io?

I think its easier and better to fix such links after downloading the md file

Maybe. I'll try soon

Maybe we should render them inside of an iframe?

Huh. Personally - I don't like iframes. Don't know for now, need to think a better solution.
Let's think about examples in separated issue https://github.com/cssinjs/jss/issues/93

navigation scrolling doesn't feels right, I would make the entire sidebar scrollbar

As you wish)))

logo text position is a bit different in the original design

You mean parallax-moving logo? Yes. I know, it's because logo uses some custom font in original design.
And our - is built with pure html and I don't want to load custom font.

what is this white arrow in the navigation on the "JSS Plugins" menu?

Hm... Menu dropdown? I thought it was explicitly :)

I would recommend this markdown parser, its the best

I'll take a look. Maybe we can drop prism.js. And check the difference between bundle sizes before and after.

We can use jss-preset-default and jss-isolate, also use jss-expand where possible (f.e. boxShadow), use jss-extend instead of spread operator

1. About jss-preset-default - yes. It was in my plan. but suddenly I became lazy :)
2. jss-expand is used where is needed. Padding, margins, etc.. Maybe you find some place where I became lazy too :)))
3. jss-extend - agree

Publish normalize as a separate package!

Ok. Good idea

[typical000]

• Entire sidebar scrollbar - DONE
• Handle internal links like ./performance.md - DONE
• Handle internal links with external property - DONE

[typical000]

Published normalize as separated package - https://github.com/typical000/jss-normalize
Maybe we can add it to external projects

[typical000]

@kof Are you ok if I do this things through Github web interface directly:

• > Change headings to right ones (e.g. on some pages there are a lot of H2, like here)
• > Remove from plugin pages JSS logo.

Because doing pull requests for all this small fixes, I think, it will be a mess :)

[kof]

yeah such small things is ok)

[typical000]

Removed JSS logo from plugins pages, changed headings. Tomorrow I'll transfer site to cssinjss org (name will be just "landing").

The last things what we need to be solve:

1. Try to use markdown-it
2. Example section. But we can do it as separated issue later, and publish stable version if examples as they are.

[kof]

maybe instead of "landing" - "site"?

[kof]

And here is react integration for markdown-it parser https://github.com/alexkuz/markdown-react-js

[typical000]

Just tried to use markdown-react-js and quick feedback:

1. Troubles with rendering images. But not just 'warnings' but empty rendered content
2. Fail in rendering "Gitter" and other links with images ([![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/cssinjs/lobby))
3. Bundle size increase

So I leaved MDComntent component as it was before. Let's change it soon when we have more time. :)
Yes, I agree that markdown-it is better. But marked solves all problems what we need to solve. :)

[typical000]

And transfered repo https://github.com/cssinjs/site
@kof can you enable static site for this repo? I have no access to 'settings' tab :)

[typical000]

Ah. I'ts already generated) https://cssinjs.github.io/site/

[kof]

hmm it seems to be enabled https://cssinjs.github.io/site

[kof]

just bought cssinjs.org and installed, in a few minutes it should work.

[kof]

I will review soon the site to see what else should be improved before we can announce it.

[kof]

After I bought the domain I found out that we can have cssinjs.github.io, which is actually also nice, because there is no dependency to external domain provider. We just need to rename "site" repository to "cssinjs" for it (same repo name as org name). But yeah as I bought cssinjs.org now its probably still nicer.

[kof]

A cool idea is to add an "edit" button to every page with the proper link, like webpack https://webpack.js.org/configuration/

[typical000]

About "edit" button - cool idea. I'll add it!

[typical000]

Anyway - updated dependencies and added jss-global to list of plugins on main site

[typical000]

@kof Added "edit" link

[cvle]

@typical000 Its better not to point to the edit feature directly because it is only available to logged in users.

E.g. currently you do:
https://github.com/cssinjs/jss/edit/master/docs/benefits.md

We should change it to:
https://github.com/cssinjs/jss/blob/master/docs/benefits.md

[kof]

@cvle github asks user to login and then redirects to that page, seems to be a good experience, no?

[cvle]

@kof I'm not sure. Personally I never use the edit feature.

A list of projects not linking to the edit page:

• https://facebook.github.io/react/docs/hello-world.html
• http://redux.js.org/docs/basics/Reducers.html
• https://flowtype.org/docs/existing.html
• http://read-the-docs.readthedocs.io/en/latest/builds.html
• http://docs.sublimetext.info/en/latest/search_and_replace/search_and_replace_files.html
• http://docs.julialang.org/en/release-0.5/manual/packages/
• https://graph.microsoft.io/en-us/docs/api-reference/beta/resources/excel

A list of projects linking to the edit page:

• https://www.nginx.com/resources/wiki/contributing/github/

Just made the list by shortly browsing the web. I think we should follow what the majority does to have a unified user experience.

[kof]

@typical000 one more enhancement, we should use pushState instead of hashes in the url. I guess its just an option in the router, right?

[typical000]

@kof If we switch from hashHistory to browserHistory we loose possiblity to share direct links to our pages.

For e.g. now if we go to http://cssinjs.org/#/benefits benefits page will be rendered.
In case of browserHistory - if we go to http://cssinjs.org/benefits - we recieve just 404 :(

[kof]

Why is that?

[typical000]

Because github dont know nothing about our app urls. And any route except
index (in our case because we have only in root of repo index.html) will
return 404.

Yes, if we load main page and navigate through pages all will work. But any
refresh willbe 404.

22 дек. 2016 г. 23:50 пользователь "Oleg Slobodskoi" <
[email protected]> написал:

Why is that?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/cssinjs/jss/issues/78#issuecomment-268898328, or mute
the thread
https://github.com/notifications/unsubscribe-auth/ACUPXYbVsctET9U_G7gxpXj6C_p-vhwCks5rKvCfgaJpZM4F4pob
.

[kof]

Hmm, can I do something using the domain provider?

[typical000]

@kof Only with domain name - nothing.
We need backend for supporting pushState. In this case we need to buy VPS hosting (or something like this) and:

1. Rewrite our server.js from simple writing HTML to full functional node.js server with react-router
2. Remove our site from gh-pages, transfer to hosting
3. Use github only as public repo. Every change pushed there we must merge manually to copy on our hosting (or write some hook, don't know)

But if we make full functional backend we can add to site real SSR rendering :)

But in terms of size and purpose of our landing site - I think this is a little "overhead".

[kof]

I don't really want this project to depend on pay-services.

[kof]

We can actually do full ssr rendering on github as well (commiting a build produced locally), but we will need to make a build for every documentation change in any repository, which is also suboptimal.

[typical000]

I think that 200kb of data loaded by user is not a big problem. We can also try to optimize resulting bundle. Maybe try webpack 2? :)

[kof]

I wasn't talking about build size, I was talking about the need to generate a new build for every change.

[typical000]

Yea, I know about what are you talking :)
But I'm talking that, maybe, we don't need to recompile anything after any *.md file changes and leave anything as it is.
Because, as for me, current build is very convenient - we don't need to recompile anything when we change docs. We need to push changes only in case if we add new pages, or change site functionality.

And only what we need is to try is to reduce bundle size. But it's only my opinion :)

[kof]

Oh so you see a way to use pushstate on github and still have documentation loaded dynamically somehow? Are you thinking of generating html files for each route?

[kof]

I think landing page is the next big priority for me. Hope to get it ready over the next days because I am on vacation.

[kof]

@typical000 can you ping me on gitter to discuss some stuff?

[kof]

The downside of having it automatically fetch the documentation from master branches is that there is no versioning. A push on master is immediately on the documentation, even if a package is not released yet.

[kof]

I think documentation should be always connected to the specific version of the libraries.

[kof]

We def. need to do something about current subnavigation, this arrow one needs to click on won't be understood.

[kof]

Another thing: I think plugins which extend the JSON API should follow next to the JSON API documentation (maybe even duplicated), so that one can read the entire syntax without to jump a lot.

[kof]

TBC #393