The Polymer custom elements (like Iron or Paper elements) have the description for each element in the comments of the HTML file of every element, description which is identical with the README.md file.
So I assume that the README.md is generated by a tool based on those details in the comments.
A tool which I also assume could be added as a gulp process.
Can anyone point how to do that?
Have a look at the Polymer CLI. It is a command-line based tool for scaffolding out new elements and projects. More information on how to install and use it can be found here
Related
This isn't a strictly programing question, I want to write some guides and documentation for my company. I've noticed that Microsoft has a page for a set of tools that help the contributors of their documentation create and edit said documentation.
It's called Docs Authoring Pack for VS Code. It's a pack of plugins that help you write documentation markdown. From reading it, it supports quite a few features such as embeding images and links to other pages.
My question is, can I use this pack to create a local html file that would work with those features. (For example linking from one page to another with the URL being a relative local path to the main page).
In VS Code I got this testing page with this plugin
I want to know if I can generate an HTML file from this that could be viewed in a browser.
I'm looking to watch HTML/CSS files and run a linter when they are saved. I'm not using a specific build systems, rather, just calling node cli's directly from my package.json file.
I'm using ESLint to take care of javascript - can anyone recommend a similar linter for HTML/CSS?
use stylelint for stylesheets and Tidy for html
I am still using the default Octopress 3 theme, but would like to use Jekyll themes The instructions online, though, suggest that I fork a theme, change the _config file, and then add my content.
It seems like, since the themes should just be sass and _layout, I should be able to install those files and have a new theme.
I haven't seen clearer examples or documentation on that.
Posting here per the jekyll website.
Generally, the best way is to fork the theme, and copy over your content in the _posts folder, and your _config file, as per this answer.
It would also be possible to copy over the theme files into the _sass, css, _includes and _layouts folders, since this is where the theme rests, but this would mean a) more work and b) you can quite easily mess it up. Oh, and the js folder, the index.html file, any other pages not using the page layout...
Ultimately, Jekyll is not like Wordpress; It's not easy to just drop in a new theme.
Forking a jekyll theme just for using it is not a good practice, even github has recognised it and now provides the template type. Forking is good mainly for contributing back to the original.
The easiest way to switch theme on an existing or new jekyll installation is to use the following plugin: jekyll-remote-theme, which is available since November 2017.
The remote_theme method is almost similar to Wordpress usability, instead of clicking around you have to type-in the name of the new theme in the config file. You do not need to fork a theme or touch any of the style files.
This is an elegant solution, because in the long term you prefer the experts (i.e., the theme maintainer) to handle bugs and new version in the theme, while you can focus on your content.
If you have a custom theme with new and elaborate layouts then the switch might take some more manual work
The Polymer Starter Kit is a good reference to start a Polymer project. You simply put all your elements into the app/elements folder. This works pretty neat for small to midsize projects.
It becomes messy when you have more than ~30 elements. Then you want to refactor the flat elements folder into a deeper folder structure like this one:
- elements
-- my-module-1
--- my-element-1-1
--- my-element-1-2
-- my-module-2
--- my-submodule-2-1
---- my-element-2-1-1
---- my-element-2-1-2
--- my-submodule-2-2
---- ...
There are a couple of issues:
when you want to demo and test submodules you need to import all dependencies above every element definition
you break the pattern of "all elements are siblings"
your relative paths become messy (lots of ../../../my-module-x/my-module-y)
you either have lots of paths like ../../../../bower_components or you use /bower_components, then you need to have a redirect in your dev-server and the absolute paths will mess up gulp-vulcanize.
With a demo and test folder for every element your directory structure grows very quickly
Here is a nice article describing the problem and pointing out two solutions:
Separate Elements Repository
Building Reusable Elements
Separate Elements Repository like in the Topeka App works for ~30 elements, but once you are up to 100+ elements, you run into the same issues.
Building Reusable Elements seems like a good idea at first, because you can encapsulate everything nicely. But working on hundreds of repos is painful, and the standard pattern breaks when you want to have more than one single element in your repo.
So I am wondering, what are good practices on how to build large Polymer apps?
Are there any examples of projects with way more than 30 elements?
What are good practices for reusable elements repos that contain multiple elements?
What is a good structure for multiple entry points?
In general: How do you scale Polymer projects?
We have a production application serving up 100's of elements. We found it useful to group multiple elements inside folders to cut down on the number of repos and folders. We still make all elements siblings.
There is a bit of precedent for this inside Google's own elements. If you take a look at app-layout and polymerfire, they both contain multiple custom elements.
The mind shift is to remember that not every element should exist in it's own directory.
It is useful to your issue to think about the difference between the file structure and the url structure. Making the web server map the files to the same place. This is what polyserve does, and you can configure wct to set up its server like it too.
So, for instance, when you are creating a single element to test, its normally sitting directly in the project directory, but the web server is mapping this parent directly directly into /components. Its doing the same with bower_components, so they appear at browser level to be at the same place. That is why references like ../polymer/polymer.html work
I'm thinking in the scenario you propose above, that you repeatedly do something similar at each submodule level so that each element can reference polymer, or its other web components at ../polymer/polymer.html
The net result would be an overall project "URL" structure that looked like
-components (elements mapped to this as well as bower_components)
--mymodule1
---(mapped so all directories under bower_components are mapped in here)
---myelement1.1
---myelement1.2
--mymodule2
---(mapped so all directories under bower_components are mapped in here)
---myelement2.1
---myslement2,2
IMO the key to organize Polymer elements goes all the way to designing the solution to problems / pages. Think of designing Lego pieces for a particular model. Yes, you can build many pieces that have very specific functions, but it will be better to focus on re-usability and design fewer pieces that will cover most of the structure (base elements) and then add some touch up pieces (touch-up elements) to finish the model. Base elements should be simple and very generic.
While the touch-up elements are not likely to be recycled, they can stay with the page. Base elements on the other hand should be placed in a folder very close to the root with very descriptive names. As development progresses, the rate of new base elements will decrease as well as time needed on developing new pages.
If the design is correct, then how you categorize elements doesn't matter, just to place them in the bower_components folder unless you are building public polymer elements. Everything in bower_components should be controlled by bower.json so you will delete the whole folder and use bower install to re-populate it.
Across the web I've found several tools regarding html to css convertors (to generate classes). a fine example is this convertor: http://primercss.com/index.php
However, I was wondering (And couldn't find by myself) if there are advanced tools that convert the html to scss - and if there are tools that I can customise the scss on the go (for example - to decide whether to nest a specific class inside another class).
I'm using in my project grunt so if there is a grunt plugin that might generate this sort of thing automatically that can also be good help.
I think you should read about this grunt plugin:
https://github.com/htmlhero/grunt-init-block
I use it on my projects and it's a very useful