Automate versioning values #222
Conversation
- add a versions module to provide the values and RegExp for injecting them - add a function in the build process to handle that replacement
- add the gulp config changes - remove ,
- tidy up definitions spacing
- remove console statement
|
+1 to this idea |
|
+1 to the idea. I don't know enough about how this code works to properly review it though :) |
|
|
||
|
|
||
| // function to inject the versions into the string given | ||
| injectVersions = function(string, versions){ |
This comment was marked as off-topic.
This comment was marked as off-topic.
Sorry, something went wrong.
|
Can I ask why you use markdown, and convert it to HTML? |
|
@AntouanK because it makes it easier to alter the design without having to modify all the content. |
|
@mikeal I see. I saw the stylus files, but it's more like hardcoded styles for a prototype, and less like proper styling for a long-living page. |
|
@AntouanK the markdown gets converted in to simple HTML which is dumped in to sections of an HTML template https://github.com/iojs/website/blob/master/source/templates/main.html |
|
@mikeal Do you have a new design coming up? Are you going to keep that md -> HTML process there also? |
|
Actually I'm going off topic. |
- propagate changes to all lang files - version fields are dynamically injected in the templates by constructing RegExp for each one of them - image link also defined in the version object to be easily changed later if needed - made code a bit more readable in the template task
|
I've completed the PR, and propagated the changes to all languages. About the injection in the template, it's now more dynamic, meaning that you can add whatever you want in the versions object and then inject it in a template with just the id and the key of the value you want. Let me know if we need something else on this PR. |
|
Good job on the formatting, that file is much more pleasant to look at now. LGTM if it works. |
# Conflicts: # content/kr/es6.md # content/kr/index.md
|
Let me resolve the conflicts on the Korean files |
- complete merge from original repo, and use new Korean files under `/ko/`
|
Files should be under Should be better though next time, to do a PR only with the |
|
@silverwind Should I ask someone to review the code? |
|
I'd squish the commits into one and wait for a project member to review. I was just commenting on code style, which looks fine to me now. |
|
Could you please change Otherwise +1 for the idea! |
|
@fhemberger Naming is a bit tricky on this one. It's a small detail anyway. |
|
@AntouanK Ah, I see. And what about changing it to a more general 'replacements' approach with a simple key-value-map? It doesn't have to be limited to replacing version numbers. What do you think? |
|
@fhemberger Sure, if we need more things to be replaced, it should be more generic. |
|
I just thought that would make it easier instead of having to maintain |
|
@fhemberger Well, all you have to change is the value and the link in one file. It's a 5 mins job. I'd suggest to merge this for now as the basis, use it for a few days/weeks, and then see what's annoying or useless and change it as needed. |
|
@iojs/website |
|
@snostorm Ok. Well yes, if you make it more generic, what I did is actually a small templating engine, so it make sense to use an existing one. |
|
The markdown files do not prevent us from changing the design. HTML templates versus content are an important distinction. As the site grows, we'll have multiple templates to allow for different sections (Guides, TC/WG updates, etc.) but inside each the articles will remain simple markdown. One main reason for this simplicity in content is the translation efforts. It is much easier to remain consistent across 20+ copies of the same content if a lot of the extra markup remains out of the mix. Plus, it is easier to see what needs to be translated. I would argue we gain more flexibility on future tweaks to the layout if the articles are written in mostly H1-H4, code blocks, pre blocks, bullet points, links, etc. This doesn't really affect our overall design strategy -- if anything, it'll help it long term. |
|
@snostorm But I've seen already many localised sites breaking because words were too big or more than one etc. We not keep the text (content) in JSON files and use HTML for templating? |
|
@AntouanK those problems usually crop up in the layout/template side of things, which will be HTML-like and we're going to allow for per-localization CSS tweaks as needed. By restricting our articles to Markdown, than we're defacto dealing with a very predictable subset of markup. They are typically block based and easily styled for a variety of scenarios. Will the homepage, download page, etc. be Markdown in the near future? Probably not. They'll grow too complex and variables will come in to play. FYI we already do have JSON files in place for defining key phrases that need translating. Over time, as we need more, I'm sure this will continue to get utilized and evolve to better handle more complex structures. (Yes, we need to make it so we can use this library of phrases from within the articles as well.) Side note: From my perspective a 100% requirement of the new (in progress) site design mockups will be that they are tested early on to be responsive our entire list of active languages. So, in the end. I agree, mostly, and I foresee the project moving more in the direction you propose, with the exception of more complex articles specifically. |
|
Fair enough. So, this PR is a bit meaningless then, adds things that are going to change anyway. |
|
Not trying to continue a conversation that may have been finished, but while reading both of your comments, I thought of Web Components as a possible solution to the problem of easily maintainable yet sufficiently complex templates. We could standardize just a few for the different page types and then optimize them for localization. Here's a few introductions to web components:
In addition, there are many existing web components that have functionality that could be useful on the website for both users of io.js and developers of io.js. Here are a few I found in about 5 minutes of searching on the registry-like component sites:
|
|
@bnb And the io.js page is a page dedicated to be seen from as many people as possible, across the globe. I wouldn't target modern browsers only in a site like this. The closest thing you can use today in production is React for me, if we are talking about using the "components" philosophy. |
|
IE9+ or 10 is generally required for the component polyfills to work . I actually am doing a lot of work which leverages the (fairly light) Problem here is we've decided to make sure Also, I'm hesitant to take a SPA approach or make too much of the content dynamic, as we'll lose out on a lot of search engine discovery. But, I do love the code encapsulation which |
|
If we are adopting a template engine solution in the future (both Handlebars and Jade were already discussed somewhere), you could also use custom template helpers or mixins to define custom blocks. So the rendered pages would still be 100% pure vanilla HTML and fully backwards compatible. |
|
@snostorm With the SPA article, I was just sharing that as an example of what could be done; I didn't intend to imply that we should use a SPA approach. Sorry if I didn't communicate clearly on that. Also, while I was looking through the various Web Components sites, I saw several mentions of a few polyfills. In general, do you know if the polyfills for Web Components not work back to IE 8? |
|
Sadly, IE8 simply does not have the technology in place to implement the registerElement polyfill without first polyfilling/faking DOM mutation events (which nobody has ever bothered to do.) |
|
Ideally, the markdown would be treated as a handlebars template after translation, so a I don't really have any problem with inserting html into the markdown for this, since that is perfectly valid. |
|
@Fishrock123 That would be an ideal approach, while I'd love to keep the HTML in the Markdown files to an absolute minimum. Although we already have an issue in #221, where it would be helpful to have a |
|
Really, the homapage itself should probably be moved to an HTML template which has some fill-in-the-blank areas. It'll have a complex enough layout eventually to warrant this. The i18n groups could then focus on just translating the phrases seen there. |
|
See #251 |
Made a draft on how to automate the versioning templating.
There is a small array that contains all the version related values, like name, version string, link and RegExp which to use when injected into the templates.
That should be very easy to change in order to build with different version.
Adding it into the gulp task is pretty simple.
Could be optimised further though.
I just made an example with the
enlang for now.Let me know if I should go through the other languages and complete the PR.