Comments (14)
Okay, I have created a layout suggestion. My thought process:
- Pages sidebar sucks. You can not give a nice menu structure
- Sidebar rules. You can give a very nice menu structure
- Add pages with long names, as they will become searchable in the pages widget
- Custom menu structure in sidebar with short titles, to easily find your way
- The pages widget seems to be closed by default when using a sidebar? That is good :-)
What do you think?
from webpack-book.
The current structure (category -> subcategory -> qa) looks ok. If/when navigation becomes an issue, something can be done about it. Architecturally speaking a system could look like this:
- The wiki would be for edits (not discovery) like now. You can of course browse through it but that's not the point.
- There would be a companion site that would get generated based on the wiki content (data structure below)
{
"category": "Basics",
"subcategory": "Getting started",
"title": "How to install Webpack?",
"content": "Do this and that...\n"
}
In addition there would be a search index for the frontend. See lunr for an example.
The discovery portion would then operate based on this data. You could for instance filter based on category or try more explicit searches (target title etc.).
Technically this isn't a big feat. I've done something similar with jswiki. The site content is generated based on the wiki using ghw, a custom tool I wrote. In this case a tool would parse through wiki pages and emit JSON.
The frontend would then operate based on that JSON and a search index generated based on it. I think a light frontend based on React could work. In addition it would require a router (likely react-router).
Even something light such as riot could work. Given it's brand new technology I haven't used it yet (released yesterday) but it might fit the bill perhaps.
from webpack-book.
This sounds awesome :-)
Suggest we use the sidebar as a temporary navigation tool for the wiki. When we have content and feedback on its usefulness we can move it to what you describe?
from webpack-book.
Great work done on JSWiki btw!
from webpack-book.
Yeah, the sidebar can remain there. No problems with that.
from webpack-book.
I did a first pass at the site. See the main repo for further info.
I think this sort of search fits better QA format. Now some matches tend to be quite big since it matches against title and content. Maybe the articles should have some metadata (ie. tags) attached to them? Then you could search against those and skip having to index content. The tags can be set up by using some convention. Ie. something like this would work:
TAGS: umd, webpack, configuration
It would be possible to parse those using marked
quite easily.
from webpack-book.
There's a live demo at http://christianalfoni.github.io/react-webpack-cookbook/ now.
from webpack-book.
Just started thinking... Maybe the nicest thing to do would be just to run the content through gitbook? I did this with Survive JS and it worked quite nicely.
from webpack-book.
Hi @bebraw, sorry for late response, I have been away on vacation for a few days.
I really liked the gitbook presentation. How does that work in regards of creating and publishing content?
The search was also cool, though yeah, that is more for Q&A. Is it possible to point it to specific pages?
I will keep adding content until we land a platform, but 👍 on gitbook :-)
from webpack-book.
Hi @bebraw, sorry for late response, I have been away on vacation for a few days.
No probs. I did some cleanup and added some new content. There are still blank pages, though. I hope you can look into those at some point.
I really liked the gitbook presentation. How does that work in regards of creating and publishing content?
It is quite straight-forward to set up. It comes with a simple cli tool that can be hooked up as a package.json
script. Then you would do something like npm run gitbook && npm run gh-deploy
to update the content. It will require book.json
(metadata) and SUMMARY.md
(TOC, points at content) but once those have been set up the process should work I think.
If you want I can set it up.
from webpack-book.
Gitbook based build is running now. See http://christianalfoni.github.io/react-webpack-cookbook/ .
Notes:
- Gitbook summary (ie. toc) gets generated based on the sidebar. It is important not to break its structure (ie. add extra newlines between lists)
- Adding special characters to page titles breaks those pages (not accessible). This is due to encoding. The markdown links get encoded but the actual filenames don't. It is quite possible to solve this but I didn't spend too much time on this yet as it's just a proof of concept.
- You should add proper introduction per section. Now I just reused some existing pages. Push the current intros to subsections of their own.
- It is possible to add more functionality to the book (ie. meta + plugins). Example from Survive JS - https://github.com/bebraw/survive-js/blob/master/book.json .
from webpack-book.
Hey! This is awesome! I really like this format, and as you say, it is possible to add more features.
I have been thinking a bit on the format of each page. I will by writing up some more today, try to keep things a bit simpler. Think of the content more as "reference page" than a "tutorial page". Very often you just want to get in and do one specific thing and the most important thing is the code examples I think.
Or maybe split things up in: Tutorials and HowTos. Anyways, we can just keep iterating and we will land on some good formats eventually.
This is really great work! I have been getting more feedback on webpack and React JS so there seems to be more interest in it these days. Good timing for a cookbook :-)
from webpack-book.
Or maybe split things up in: Tutorials and HowTos. Anyways, we can just keep iterating and we will land on some good formats eventually.
Maybe this could be reflected in the sectioning somehow. Current ones (basic, advanced, theory) don't tell a lot. How about React? The cookbook should be about Webpack and React after all. Here's a sectioning that would make sense to me at the moment:
- Getting Started with Webpack - complements official getting started tutorial for Webpack
- Running a workflow
- Loading files
- Writing loaders
- Webpack and React
- Setting it up (hot loader, es6 etc.)
- Flow
- Authoring libraries
- ???
- Going to Production
- Structuring configuration
- Hashing etc. - Rename (currently Dealing with production)
- ???
You could either read this linearly or just pick the parts you find interesting. For instance if you are already familiar with Webpack, perhaps you would like to read just production bits. Or if you are new to React, start from there.
Once the structure starts to stabilize and we have content together, it would make sense to write concrete code examples for various parts in the repo.
from webpack-book.
I suppose we can close this now.
from webpack-book.
Related Issues (20)
- Enhance section on Hot Module Replacement HOT 7
- Purifying CSS when using React HOT 1
- request to translate into Indonesian HOT 1
- webpack 4 HOT 8
- Autoprefixing missing sample HOT 3
- Error on annotate-console-log syntax and annotation problem HOT 4
- Copybody Corrections HOT 2
- extract-text-webpack-plugin doesn't extract a file HOT 2
- developing - images directory had incorrect path HOT 1
- report one code error HOT 1
- building - tidying up - [email protected] replace default export with named export HOT 2
- favicons-webpack-plugin outdated dependencies HOT 1
- ew HOT 1
- Feed back and suggestions HOT 3
- Separating CSS: Code not working HOT 3
- WebSocket connection to 'ws://[::]:8080/wps' failed HOT 2
- in safari, not passing host fails the live reload of code HOT 2
- dynamic import about terser error HOT 16
- "watch" script throwing an error HOT 4
- css-loader now supports absolute imports
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from webpack-book.