assemble
Tracking Version 0.3.0
Complete refactor.
This issue is for tracking progress against assemble-docs v0.3.0. This is a complete refactor.
I will be updating these issues, and the TODO's as we make progress. Please feel free to add your comments. There is still a lot to do, if you want to roll up your sleeves and help out, we'd love to have you! Pull requests are always greatly appreciated!
General goals
In general, the goals for this refactor are:
- [x] generate the entire site with Assemble as before, but make the structure of the project an ideal way for newcomers to learn how to use Assemble. This has not been the case to date. Marking as done since the structure is already much better.
- [ ] do a better job of welcoming newcomers and designers to Assemble. This means the content needs to be much more designer-friendly, and we need to have a much better introduction/getting started guide and documentation (see https://gist.github.com/jonschlinkert/9450158. this is just a start), some tutorials, a blog and ideally some videos.
- [ ] better flow and transitions from section to section
- [ ] better design for the home page (we might get some awesome custom icons from iconic!)
- [ ] search. this might be challenging to do side-wide, but we filtering on each page would be a great start
- [ ] add links to blog posts, tutorials and other write-ups about Assemble. Let us know if you've written one! Or if you happen to read one, we'd appreciate it if you could add a link to it here
Sections
See https://gist.github.com/jonschlinkert/9452935
Config
- [x] Use
.assemblercfor global config, to make site variables easier to maintain - [x] utility script to pull down Assemble's package.json, so the metadata can be passed to templates.
Plugins
Most of these will be published to their own projects (some are already), but I'm testing them here first. Any feedback/help in maintaining these as contrib plugins would be welcome:
- [ ] search/filtering - initially filtering on each page, ideally site wide
- [x] navigation plugin to automatically generate sidenav on each page
- [x] anchors plugin to add linkable anchors to each section
- [x] "link to source" plugin, to automatically generate a link to the source code for each section / file
- [ ] link-checker.js (courtesy of less.js / @lukeapage) - this is added, but still need to add credit to Luke in banner
- [ ] 404 / holder.js plugin (courtesy of less.js / @lukeapage) needs attribution in banner
- [x] download plugin, to automatically pull down docs from other repos, helper docs in particular (usually
.zipfiles, can be anything) - [x] decompress plugin, to expand the zip files pulled down with the download plugin
Helpers
Same as with plugins, some of these will get their own repos. Some existing helpers will get upgraded with these.
- [ ] Page-level TOC for helpers/sections, accessed in the "content navbar". We can use the TOC plugin for inspiration, or tweak it to do what we need here.
- [ ] Global TOC. The TOC plugin is for a specific page, so we need a different solution.
- [x]
basename: https://github.com/assemble/assemble-docs/blob/v0.3.0/structure/includes/head.hbs#L8 - [x]
console: https://github.com/assemble/assemble-docs/blob/v0.3.0/structure/pages/helpers.hbs#L17 - [x]
content: read a file, parse front matter and add it to the context, compile templates, convert markdown to HTML and return the content. https://github.com/assemble/assemble-docs/blob/v0.3.0/structure/pages/helpers.hbs#L18. this will likely be used to upgrade this {{md}} helper - [x]
expand: https://github.com/assemble/assemble-docs/blob/v0.3.0/structure/pages/helpers.hbs#L15 - [x]
isActive: automatically addactiveclass for link representing current page https://github.com/assemble/assemble-docs/blob/v0.3.0/structure/includes/list.hbs#L5 - [x]
resolve: used in links, this automatically resolves the correct path to destination files. it's nice because it works with permalinks as well. https://github.com/assemble/assemble-docs/blob/v0.3.0/structure/includes/list.hbs#L6. - [x]
join: simple array join - [x]
markdown: block helper to convert to markdown. the current markdown helper in handlebars-helpers will get updated with this - [x]
news: helper to add news/updates to the site. we could use a jquery rotator, or just show the las three items or something - [x]
read: - [x]
replace: - [x]
write:
scripts / jquery
- [ ] quote rotation. we have a lot of quotes from users on twitter, etc. need something to rotate quotes
tbc
Are you in need of any design related work with this PR? If not, I will gladly read though and edit documentation.
I'm open to any kind of pr, although documentation in particular needs attention badly
Sent from my iPhone
On Mar 12, 2014, at 12:23 AM, Patrick Burtchaell [email protected] wrote:
Are you in need of any design related work with this PR? If not, I will gladly read though and edit documentation.
— Reply to this email directly or view it on GitHub.
:+1: great thanks! everything looks great. don't revert the commit, I guess the prefixer is something we could probably do without since we use less than 0.8% of our site visits come from IE 8 and lower (and we use less.js, so mixins should cover everything modern). But... given that it's a build step and we'll be using uncss, let's just leave it. At least the 0.8% might have a better experience.
Thanks a lot!
btw, I know there hasn't been a lot of direct activity on assemble from @doowb and I recently, but we are working on assemble - can't say a lot yet but I think you'll be happy with what you see!
No problem! Also, autoprefixer is great for checking to make sure you have all prefixes for all browsers in general. For example, when I get started on the homepage, I'll probably end up using Flexbox for some of the layout. Since the spec for Flexbox can be different between browsers, autoprefixer is a great tool to take care of it —which is the main reason I added it.
Yeah, agreed it's a nice tool. We're probably going to either use autoprefixer in v2.0 of less.js or use it in a supported plugin for less.js.