sourcejs / source Goto Github PK
View Code? Open in Web Editor NEW[ON HOLD] Living Style Guides Engine and Maintenance Environment for Front-end Components. Core repository.
Home Page: http://sourcejs.com
License: MIT License
[ON HOLD] Living Style Guides Engine and Maintenance Environment for Front-end Components. Core repository.
Home Page: http://sourcejs.com
License: MIT License
We're working on specs API that will contain parsed information from all spec example sections (with HTML) and all information about spec pages (from info.json).
Here's first example of API usage http://youtu.be/cefy_U5NU4o. In video, you can see that Design-lego tools takes navigation tree from Source specs API and draws selected elements from example section in working space.
If you want to get some specific API queries, please drop your thoughts in comment below.
Recommended setup for using Source is to keep two git repos - first is Source repo, second contains all specs in public folder. For now, we have files that aren't stored in any repo and are git ignored by default in Source, those files are stored in /user
folder and /client-side/plugins
.
I'm thinking about moving all files that are now git ignored in Source to another common folder with /public
contents to unite them in one repo. This will make sync process in team much easier, all setting files will be in repos and we'll be able to deploy Source to remote through git.
As I see, the only downside of this refactoring is that repos with specs must be restructured this way:
//specs repo
user
specs
//from Source
docs
core
test
//user spec catalogues ant settings
main
user
To leave a possibility to use custom settings on each setup, we can add custom git ignored options, where path to /user
could be overridden.
Also, maybe someone have thoughts about renaming /user
folder, this folder is used for custom client and server side settings that are overriding default Source settings.
Redirecting from host shortlink, say, 'source' to localhost:8080 can be perfomed by the following command:
netsh interface portproxy add v4tov4 listenport=80 listenaddress=127.0.0.1 connectport=8080 connectaddress=YOUR_LOCAL_ADDRESS
Place Clarify Helper panel in Shadow DOM with scoped CSS to prevent conflicts with examples styles.
I'm thinking about integrating some of this tools https://github.com/nevir/groc http://jashkenas.github.io/docco or JSDoc based compiler into Source Spec pages.
With this kind of integration, we could get auto-generated JS docs right inside our Source Spec pages with access to all Source plugins.
Make available to use different languages in search with transcription using latin letters and vice versa.
example:
you search "lenta" - you get "лента"
you search "триггер" - you get "trigger"
Link proposal service, based on your (incorrect) url request
Hi,
Would be great to prevent blinking source code, when using <code class="src-html source_visible"></code>
, showing only formatted version with prism, when it's ready.
Also, we need to check if code examples drawing is delaying final Spec Ready event, to keep scrollToHash
working properly. Check http://sourcejs.com/docs/api/load-events/
Hi! Trying to pass GET params to spec causes error, for example:
Debugged and found Source/core/middleware/read.js
line 16:
var physicalPath = global.app.get('user') + req.url;
and line 75:
var requestedDir = req.url;
then correct it to:
var physicalPath = global.app.get('user') + req.path;
var requestedDir = req.path;
Currently, project.css base styles for typographic elements (p, ul, li, small etc.) in .source_example
blocks are overridden by default.css.
These elements are being styled via the following properties in reset.less, and are not overridden by project.css due to it being linked earlier in the document:
// reset.less
body {
...
font: 14px/1.5 Arial, Helvetica, sans-serif;
color: #333;
...
}
font
and color
can be declared on html
so that users declaring those properties on their own html
element can easily override them.
Furthermore, core.css is, by default, linked after project.css.
This does the following:
This is the solution I've gone with for now.
My project.css is now applied across all my spec pages, and there is no issue with basic typographic elements inheriting Source styles (since all typographic elements are now styled via project.css).
This has the added bonus of making the spec more consistent with the theme of the project.
If this is the preferred solution, I'll be happy to add it to the documentation.
I've attempted some combinations of selecting everything except for the contents of .source_example
to apply Source styling to no avail:
:not(.source_example) {
font: "..."; // Source base font styles
color: "..."; // Source base colours
}
I'm not sure if someone else can come up with something using :not
that works - this would be the most elegant solution, and wouldn't require any amendments to documentation or work after initiating a Source instance.
Move base styles, and styles applied to naked elements (without classes), to a separate css file which is linked before project.css
Do not apply any styles directly to any elements that do not have a source_
class, or are not immediate children of a source_
class.
i.e. font
and color
in core.css / default.css are only ever applied in the following manner:
.source_section > p,
.source_section > small,
.
.
. {
font: "...";
color: "...";
}
etc.
This may turn out to be a maintenance nightmare, and will have strange side effects should a user surround a paragraph in a div in their documentation.
I may be missing something huge here, so feel free to correct me if I'm wrong!
// end of blog post
Create yeoman generator for Source init instead of running grunt init
. Refactor some file structure for easier first setup.
Add configuration scenario to add this kind of Interactive Specs as a dependency from separate repo https://github.com/sourcejs/styles.
Among plugins, Source could have custom pages (small application) for different team needs. After Styles page will be also release Graphics page and Front-end resources management dashboard.
I have some ideas for creating Source as service and hosting private and public documentations.
The workflow with Source as service could look like this:
Client "feeds" their repository with public contents and gets private space for documentation based on Source engine. Also, there could be some integrations with Dropbox Storage API.
What do you think about it?
Some cases can make you to have following error:
<approot>/node_modules/jsdom/node_modules/contextify/node_modules/bindings/bindings.js:91 throw err
Error: Could not locate the bindings file. Tried:
<approot>/node_modules/jsdom/node_modules/contextify/build/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/build/Debug/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/build/Release/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/out/Debug/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/Debug/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/out/Release/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/Release/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/build/default/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/compiled/0.10.28/linux/x64/contextify.node
at bindings (<approot>/node_modules/jsdom/node_modules/contextify/node_modules/bindings/bindings.js:88:9)
at Object.<anonymous> (<approot>/node_modules/jsdom/node_modules/contextify/lib/contextify.js:1:96)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.require (module.js:364:17)
at require (module.js:380:17)
at Object.<anonymous> (<approot>/node_modules/jsdom/lib/jsdom/browser/index.js:17:21)
at Module._compile (module.js:456:26)
Typically it is caused by node_modules
folder copying to another location (deployment or smth like that).
It can be solved by the following steps:
cd <approot>/node_modules/jsdom/node_modules/contextify
npm i
Please follow this link to get more details.
Add a possibility to draw navigation from nested catalogues without index.html
on same level (buttons):
docs/
├──base/
├──buttons/
├──promo/
├──basic/
now it's possible only with this structure:
docs/
├──base/
├──buttons/
├──promo/
├──basic/
├──index.html
Also, there must be a possibility to have few catalogues with same name, like:
docs/
├──base/
├──buttons/
├──promo/
├──custom/
├──buttons/
That would be generated from this hooks:
<div class="source_catalog" data-nav="base/buttons"></div>
<div class="source_catalog" data-nav="custom/buttons"></div>
Like in pattern lab http://demo.patternlab.io/?p=organisms-article-body http://d.pr/i/4U02
Client-side development mode with special options, for disabling some Source plugins in dev mode. The same modes functionality will be used to turn on some dev plugins in the production mode.
Inner navigation changes url to index.html
in pages with different names like index2.html
. Need to get rid off index.html
dependency.
Apply tests with jasmine and dalek.js to all core functionality
.src
files support will free us from copy/pasting common parts of spec pages like resources in <head>
and Source header/footer, as we do now in .html
files.
Data for custom parts of included content will be regulated from info.json
file next to index.src
.
As this files will be processed through node.js (with ejs templating engine), soon we will have a possibility to write a markdown markup directly in Spec Pages under .src
extension.
Right now, to isolate SourceJS UI styles from source_example
blocks, we generate complex CSS selectors with Less. Would be great to replace this in future with Shadow DOM, as these guys are doing http://styleguide.sc5.io.
Fix scroll to section in cases where page is loading slower than scroll navigation + loader for spec page to get rid of nasty page jumps.
It seems like /client
isn't a best name for folder with client side part of Source engine, we have some thoughts about renaming it to:
What do you think about it?
With custom, abstract commands like:
sourcejs run
sourcejs deploy
Which will take current run folder as user
.
Moving SourceJS to global module, will probably help to install it much easier to understand.
I'm looking at using Source for a new project, and have been trying to work out the workflow with regards to creating and updating specs, as well as the non-spec templates found in client/init/
.
This is my understanding of some of how Source works:
grunt update
minifies and copies only the files found under client/src/
to public/
grunt initClient
copies the files from both client/src/
and those from client/init/user
to public/
public/
is the build folder, and is therefore gitignoreduser/
holds user specific settings, and is therefore also gitignoredFrom this it seems as though this should be my workflow:
client/src/docs/
grunt runWatch
to watch for changes in client/src/
to dynamically build public/
client/init/
, and then run grunt initClient
Is this the correct approach in using Source?
So far we got live-search results in main input field.
Few improvements to suggest here:
Last changed date from local file is not stable, and easy to lose. We're going to implement git dates support.
.src
files support to all level pages in Source.src
filesindex.html
across all Source code, replacing it with higher abstraction - specPage
.html
-> .src
Create grunt task for Source server side deploy on remote server
Calling
<div class="source_catalog" data-nav="base">
We need to get
<div class="source_catalog" data-nav="base">
<h2 class="source_catalog_title"><a class="source_a_bl" href="{base.url}">{base.title}</a></h2>
<div class="source_catalog_tx">{base.description}</div>
<ul class="source_catalog_list">
{base.specs}
</ul>
</div>
Where
base/
catalogue specsWe're planing to record some screencasts about Source workflow, which topics do we need to cover most?
Source works nice when you have one CSS (main product styles) and want to apply it different HTML elements, thanks for this 👍
Our main product has different skins (logos, css) for different customers and i want to use source for skins system documentation.
First I'm want to solve such problem - i have one HTML code and want to apply different CSS skins to it. Idea is to show how template page (core/view/skins.ejs) looks with different styles (/skins/ sub folders).
To demonstrate i created simple project https://github.com/ashmigelski/sourcejs-skins-viewer compatible with current v.0.4.0 branch. It uses very straightforward logic - every skin is a spec with info.json and
index.src inside.
Any tips or suggestions how to make it easier and more efficient? Thanks
h1 & h3 heading inside of the .example_code section get's parsed as a Section Heading for the nav
Ребят, плохо с английским, опишу на русском.
Хотелось бы видеть историю изменения блока. От версии к версии бывает блоки меняются, нужно оповещать разработчиков об этих изменениях. А так же возможность сравнить эти изменения.
Должен быть механизм draft'ов. То есть разрабатываемый блок весит в draft пока не пройдет разработку, согласование, тестирование. После уже переводим в статус published и делаем оповещение разработчиков.
This involves preview showing as well
If somebody is facing problems with installing JSdom dependency for SourceJS engine on Windows, the easiest way to solve it, is to use already built binaries:
jsdom
dependency from package.json
and run npm i
jsdom_binaries/node_modules
to sourcejs/node_modules
, replacing old foldersThe problem comes when npm install
downloads JSdom and tries to compile it locally, having xcode command line tools on OSx everything goes fine, but Windows by default doesn't have necessary tools for JSdom compilation and installation fails.
If you still want to compile binaries on your machine, or mentioned built binaries does not help, check official solution from JSdom https://github.com/tmpvar/jsdom/tree/1.5.0#contextify and alternative with node-gyp
set-up instructions https://github.com/TooTallNate/node-gyp#installation.
You can also find some help with Windows set-up in this topic sourcejs/sourcejs.com#1.
JSDom is already planned to replace with Cheerio in SourceJS 0.6.x #99.
Using spec screenshots from API #28, create secondary layout for specs navigation (http://sourcejs.com/docs/) with preview.
Are you guys open to pull requests?
If so, should I issue pull requests from a topical branch straight into Source's master?
Seperating those scripts we could use them as a light lib for any generated Style Guides.
We have some live templates collection with fast snippets to work with Source that need to be shared with public and published in separate repository.
Setting my user/options/options.json to include:
"common": {
"pathToSpecs": "../styleguide"
}
so that in my projects I can gitignore the Sourcejs folder and have the following structure:
/ -
|- Sourcejs (ignored / not commited / setup by script)
|- styleguide (Generated public folder, with core/ copied)
|- etc ...
The generated pages tree json has broken links (e.g. ocs/buttons).
The issue can be rectified by changing as in this commit.
It would be great to make more personalized service using user spec search requests. Output can be built / sort by request weight.
Search settings can be saved in local account storage.
http://sourcejs.com/docs/data-nav/index.src
Can't find spec in nested catalogues through search in tolbar.
docs/
├──base/
├──spec/
├──buttons/
├──promo/
├──index.html
├──index.html
├──index.html
With this structure, search won't promo/index.html
.
Problem lies in parseFileTree.js
, that returns nested object for live complete plugin that search is using. getAllPages
must return flat object, and if there are few kind of same named folder, the parent folders must be added to spec name in the object.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.