Dev - Display Index Pages Correctly

[simon04]

In the menu, the page https://webpack.js.org/concepts/ is shown as "Introduction" w/o listing its subsection such as https://webpack.js.org/concepts/#entry or https://webpack.js.org/concepts/#output.

Proposed changes:

• Introduction → proper page title (such as "Concepts" in the example)
• list subsections as for all non-index.md pages

Screenshot:

[skipjack]

@bebraw is there anyway to access the index page's data? I'm not even sure we're parsing out the anchors for index pages as of right now...

[bebraw]

@skipjack The current logic might skip indices, yeah. Most likely processPage should apply to those as well or we have to add processIndex (probably a better option).

[skipjack]

Is processIndex supported by antwar? Just looking at the config I figured processPage was applied to everything:

[bebraw]

Is processIndex supported by antwar? Just looking at the config I figured processPage was applied to everything:

No support yet. processPage doesn't get applied against the indices.

[skipjack]

Ah ok, would you like me to create a ticket over at antwar for this as well?

[bebraw]

Sure, open tickets. Easier to keep track of things.

[rouzbeh84]

I'm not familiar with the antwar/build process of this so, while in no way a long term solution, how do you all feel about this interim hotfix?

---

Concepts

webpack is a module bundler for modern JavaScript applications. When webpack processes your application, it recursively builds a dependency graph that includes every module your application needs, then packages all of those modules into a small number of bundles - often only one - to be loaded by the browser.

It is incredibly configurable, but to get started you only need to understand Four Core Concepts: entry, output, loaders, and plugins.

This document is intended to give a high-level overview of these concepts, while providing links to detailed concept specific use-cases.

Entry

webpack creates a graph of all of your application's dependencies.
The starting point of this graph is known as an entry point. The entry point tells webpack where to start and follows the graph of dependencies to know what to bundle. You can think of your application's entry point as the contextual root or the first file to kick off your app.

Expand Quick View

In webpack we define entry points using the entry property in our webpack configuration object.

The simplest example is seen below:

webpack.config.js

module.exports = {
  entry: './path/to/my/entry/file.js'
};

There are multiple ways to declare your entry property that are specific to your application's needs.

Learn more!

---

Output

Once you've bundled all of your assets together, you still need to tell webpack where to bundle your application. The webpack output property tells webpack how to treat bundled code.

Expand Quick View

webpack.config.js

const path = require('path');

module.exports = {
  entry: './path/to/my/entry/file.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'my-first-webpack.bundle.js'
  }
};

In the example above, we use the output.filename and the output.path properties to tell webpack the name of our bundle and where we want it to be emitted to.

T> You may see the term emitted or emit used throughout our documentation and plugin API. This is a fancy term for "produced or discharged".

The output property has many more configurable features, but let's spend some time understanding some of the most common use cases for the output property.

Learn more!

---

Loaders

The goal is to have all of the assets in your project to be webpack's concern and not the browser's. (This doesn't mean that they all have to be bundled together). webpack treats every file (.css, .html, .scss, .jpg, etc.) as a module. However, webpack only understands JavaScript.

Expand Quick View

Loaders in webpack transform these files into modules as they are added to your dependency graph.

At a high level, they have two purposes in your webpack config.

1. Identify what files should be transformed by a certain loader. (test property)
2. Transform that file so that it can be added to your dependency graph (and eventually your bundle). (use property)

webpack.config.js

const path = require('path');

const config = {
  entry: './path/to/my/entry/file.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'my-first-webpack.bundle.js'
  },
  module: {
    rules: [
      {test: /\.(js|jsx)$/, use: 'babel-loader'}
    ]
  }
};

module.exports = config;

The configuration above has defined a rules property for a single module with two required properties: test and use. This tells webpack's compiler the following:

"Hey webpack compiler, when you come across a path that resolves to a '.js' or '.jsx' file inside of a require()/import statement, use the babel-loader to transform it before you add it to the bundle".

W> It is important to remember when defining rules in your webpack config, you are defining them under module.rules and not rules. However webpack will yell at you when doing this incorrectly.

There are more specific properties to define on loaders that we haven't yet covered.

Learn more!

---

Plugins

Since Loaders only execute transforms on a per-file basis, plugins are most commonly used (but not limited to) performing actions and custom functionality on "compilations" or "chunks" of your bundled modules (and so much more). The webpack Plugin system is extremely powerful and customizable.

Expand Quick View

In order to use a plugin, you just need to require() it and add it to the plugins array. Most plugins are customizable via options. Since you can use a plugin multiple times in a config for different purposes, you need to create an instance of it by calling it with new.

webpack.config.js

const HtmlWebpackPlugin = require('html-webpack-plugin'); //installed via npm
const webpack = require('webpack'); //to access built-in plugins
const path = require('path');

const config = {
  entry: './path/to/my/entry/file.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'my-first-webpack.bundle.js'
  },
  module: {
    rules: [
      {test: /\.(js|jsx)$/, use: 'babel-loader'}
    ]
  },
  plugins: [
    new webpack.optimize.UglifyJsPlugin(),
    new HtmlWebpackPlugin({template: './src/index.html'})
  ]
};

module.exports = config;

There are many plugins that webpack provides out of the box! Check out our list of plugins for more information.

Using plugins in your webpack config is straight-forward, however there are many use-cases that are worth discussing further.

Learn more!

[skipjack]

@rouzbeh84 I do kind of like this idea for index pages however it doesn't really fix the issue of "Introduction" links not displaying their anchors in the sidebar. Although I guess if we did it this way then the anchor links would just be repetitious so maybe this is an alternative. It would change things a bit as all index pages would basically just contain a lead-in and then the rest of it would be populated dynamically based on the other pages in the section. @simon04 what do you think?

#980 will be merged soon, like hopefully tomorrow if we can resolve the last few things, so it might not be long until we can get the fix we discussed initially in.

[rouzbeh84]

@skipjack While I agree that it doesn't solve this issue I don't think it's bad that index pages would essentially become brief intros w/hotlinks to the section as a whole I guess? I do see that some Intro pages are wildly diff (i.e. /guides v /api v /concepts etc) possibly making a 'one size fits all' solution a bit more difficult...

Would the 'Introduction' page have to just nest the sections itself as an alternative to replicate how other sections in the sidebar are handled/displayed? I know I've mentioned this before and one day I'll learn more about it but can 'Introduction' aggregate all header level links into its own dropdown?

[skipjack]

While I agree that it doesn't solve this issue I don't think it's bad that index pages would essentially become brief intros w/hotlinks to the section as a whole I guess? I do see that some Intro pages are wildly diff (i.e. /guides v /api v /concepts etc) possibly making a 'one size fits all' solution a bit more difficult...

Yeah "one size fits all" would probably be tough but maybe keeping an index.md and specifying one of a few "templates" would work. Something like this could be done in phenomic I think but not in our current setup.

Would the 'Introduction' page have to just nest the sections itself as an alternative to replicate how other sections in the sidebar are handled/displayed? I know I've mentioned this before and one day I'll learn more about it but can 'Introduction' aggregate all header level links into its own dropdown?

We do have access to all the page data from anywhere we want so you wouldn't have to hardcode this, if that's what you're asking. I don't really think a dropdown is the way to go (although maybe I'm not understanding how it would be used) but I think what you showed above, without the "Expand Quick View" sections could work. Simply showing the title of each article, first paragraph, and a link to jump into it.

[skipjack]

Either a port or #980 should solve this -- let's track in #1380 though I did link back here so we can reference the screenshots and @rouzbeh84's idea. We can always re-open if it would be helpful once we start a fix.