Documentation

[vralle]

Feature request

Enhance the quality, readability, and usability of the README.md file to ensure better understanding and engagement from users and contributors.

What is motivation or use case for adding/changing the behavior?

The current Markdown documentation file, exceeding 200 KB in size, presents several challenges:

1. Performance Issues with Editors:

   Many code editors struggle to handle large files efficiently. This leads to slower loading times, lags, and overall inconvenience during editing, significantly impacting developers' productivity.

2. Navigation Challenges:

   The extensive size of the document makes it difficult to locate specific sections quickly. This lack of clarity leads to frustration and inefficiencies for both developers and users trying to understand or contribute to the project.

3. Maintenance Complexity:

   Managing and updating a large file becomes increasingly difficult over time. It is prone to errors, inconsistencies, and duplicate information, making it hard to maintain.

Describe the solution you'd like

Proposed Improvement Plan

1. Introduce a Markdown Linter:

   • Purpose: Ensure consistency and adherence to best practices in the Markdown file.

   • Benefits: Improves readability, enforces formatting rules, and reduces errors.

2. Divide the Documentation into Sections:

   • Action: Split the large file into multiple smaller files, each dedicated to a specific topic or aspect of the project (e.g., Introduction, Installation, Usage, API Reference, and Contribution Guidelines).

   • Benefits:

     • Enhances clarity and ease of navigation.

     • Simplifies updates as developers can focus on specific sections without impacting the entire documentation.

3. Retain the Original File as an Alternative:

   • Action: Maintain the current full documentation file as an optional, consolidated version for users who prefer a single file.

   • Benefits: Provides flexibility for different user preferences while solving the existing challenges for developers.

By implementing this plan, the documentation will become easier to use, maintain, and contribute to, ensuring better accessibility and efficiency for developers and users alike.

If I am asked how I envision the organization of the documentation, I look at it as follows: https://github.com/DavidAnson/markdownlint/tree/main/doc

Describe alternatives you've considered

Developers should use more powerful workstations and skills that can help them quickly solve problems in file documentation that is more than 81,000 characters long.

Additionally

I have implemented the first point of the plan. I introduced a Markdown linter and formatted two main documentation files. The source code of the files has become more readable. Some grammatical corrections were made.

Additionally, removed id attributes from named anchors. Why: stackoverflow/Cross-reference (named anchor) in markdown Github/Basic writing and formatting syntax/Custom anchors

The results of the changes are currently there: https://github.com/vralle/html-bundler-webpack-plugin/blob/feat/lint-markdown/README.md

I hope to receive some feedback/review on the results, after which it will be possible to decide on further actions.

Appreciation for the useful project

• [x] After the feature is implemented, do not forget to give a star ⭐

[vralle]

When considering the implementation of markdownlint, it is worth mentioning the specifics of combining markdownlint and prettier: https://github.com/DavidAnson/markdownlint/blob/main/doc/Prettier.md

I have nothing more to add on this topic, as I use the faster and more advanced dprint as my primary linter.

Additionally: Performance Benchmarks Biome vs Prettier vs Dprint

[webdiscus]

Hello @vralle,

Thank you for your efforts to improve the documentation.

Over 3 years, the documentation has truly grown to incredible sizes. At the same time, I tried to describe as many features as possible in the documentation and do it briefly.

With so many features, it's difficult to devote enough time to continually improving the documentation. I focus more on implementing the features.

I have long been looking at organizing large documentation on a separate site, for example, as it is done in Jest using Docusaurus. This would be the best solution. This is my goal.

But at the moment, breaking a monolithic document into separate files is a significant improvement in managing documentation on GitHub. Any help is welcome.

For NPM, I have already made a short "teaser" readme with a link to full Docs on GitHub.

P.S.: This plugin is not popular in Open Source projects, since I do not actively promote it. For the most part, this plugin is used in closed source in different companies, in particular where I work.

[webdiscus]

removed id attributes from named anchors

many years ago I already made links without id, but I encountered problems either on NPM or on Github itself: without id attribute, the links did not work. Perhaps this has changed over time.

[webdiscus]

As recommended on stackoverflow/Cross-reference (named anchor) in markdown:

Markdown doesn't seem to mind where you put the anchor point. A useful place to put it is in a header.

We can write anchor in a headline:

- <a name="install"></a>
- ## Install and Quick start

+ ## <a name="install"></a> Install and Quick start

[webdiscus]

80 chars per line was OK for the 198x era, but not in the 4K monitor era ;-) 80 chars for markdown containing many links is too little. I know, many uses 13" notebooks, but today 4K - is minimal standard for developers.

I use 120 chars as visible vertical line to manual break a long line and 180 chars for hard break.

The line length limits should be:

  "line-length": {
     "line_length": 120, // optimal minimal length
     "code_blocks": false,
     "headings": false,
     "tables": false
   },

[webdiscus]

In any case I will merge your PR with markdown linting as is. Then we can improve and optimise it.

[vralle]

{
  "code_blocks": false, // - not check fenced code blocks
  "headings": false, // - not check headings, because you can't use new line
  "tables": false // - not check tables
}

[vralle]

80 chars per line was OK for the 198x era, but not in the 4K monitor era ;-) 80 chars for markdown containing many links is too little. I know, many uses 13" notebooks, but today 4K - is minimal standard for developers. I use 120 chars as visible vertical line to manual break a long line and 180 chars for hard break.

The recommendation to keep line lengths in Markdown files (and other text files) under 80 characters is rooted in both historical and practical reasons:

Readability: Shorter lines are easier to read, especially when working with plain text editors. They allow the content to flow naturally without requiring horizontal scrolling.

Compatibility: Many tools, terminals, and editors are designed with a default width of 80 characters. Following this guideline ensures your content is displayed correctly across different environments.

Version Control: When using tools like Git, shorter lines make it easier to review changes. Diff tools show line-by-line differences, and shorter lines keep these changes clear and manageable.

Collaboration: In collaborative projects, adhering to an 80-character limit makes it easier for contributors using different setups to work together seamlessly.

Accessibility: For those using assistive devices or reading on smaller screens, shorter lines improve the user experience.

By sticking to this guideline, Markdown files remain consistent, clean, and versatile across a wide range of use cases and systems.

[webdiscus]

The recommendation to keep line lengths in Markdown files (and other text files) under 80 characters is rooted in both historical and practical reasons

Even - historical reasons but not practical.

Readability: Shorter lines are easier to read, especially when working with plain text editors. They allow the content to flow naturally without requiring horizontal scrolling.

Nobody read source markdown, but rendered html has dynamic width.

Many tools, terminals, and editors are designed with a default width of 80 characters. ... it easier for contributors using different setups to work together seamlessly.

I know, but:

• Nobody use a terminal to edit markdown
• 80 characters was standard for IDE in 80s-90s.
• Today is not actual, since developers can use modern 4K 32" monitors.

For many modern developers, 80-character per line, is on the contrary, a serious limitation.

[vralle]

We can write anchor in a headline

I'm not sure.

Custom anchors:

Custom anchors are not considered by the automatic naming and numbering behavior of automatic heading links.

[webdiscus]

We can write anchor in a headline

I'm not sure.

ok, at least for me locally, markdown-it renders anchor in a headline into html correctly and it works fine.

To preview the changes in the readme file, I use github-readme-preview. It runs locally, and I see a 1:1 rendering of how it will look on GitHub.

[vralle]

Section links can be considered instead

[vralle]

I have an idea. You or I could create a separate temporary repository for docs where we could apply any experiments. What do you think?

[webdiscus]

Yes, that's a good idea. Here is the html-bundler-docs repo for the documentation.

[webdiscus]

@vralle Can you please try GitHub Readme Previewer? I created it specifically for GitHub README.md files to provide a WYSIWYG experience.

For example, this is editing README.md looks like:

Code and GitHub blockquote highlighting:

Table:

P.S: The README file for this plugin is written using this previewer. I can't even imagine how it's possible to edit GitHub README file without a previewer like this.

[vralle]

I can't even imagine how it's possible to edit GitHub README file without a previewer like this.

vscode has live markdown preview out of box and GitHub Markdown Preview extension additionally

Default:

[webdiscus]

• VSCode markdown viewer - looks unlike original GitHub
• GitHub Markdown Preview - better (95% as my previewer), CSS is outdated and looks a bit different, but it is quite enough. This is a very good extension.

Both do not render GitHub blockquotes.

P.S. But it's better to have something than nothing.

[webdiscus]

I tried to use docusaurus. It's allow easily organise the structure / navigation. Docusaurus works with .md, .mdx files.

Here paar dummy pages:

I will create a basis structure, then we can works with docusaurus.

The generated pages I will deploy on GitHub Pages.

[vralle]

@webdiscus, I suppose that the main issue with the documentation is its overwhelmed. The website won't solve this problem, although it will be an interesting experiment.

[webdiscus]

For a one-page doc, yes, it's overwhelmed, although it doesn't fully describe all the features. Many use cases aren't documented yet.

Docusaurus solves this problem. We can good organise the structure of document to split large doc sections into small. Moreover, Docusaurus supports the search.

But, Docusaurus will be on finish, firstly we need split this readme on logical sections.

[vralle]

Hello @webdiscus!

Can modified documentation be used to improve types?

Example for:

## `preprocessor: Preprocessor` Templating engine

```ts
type Preprocessor =
  | TemplatingEngineName
  | TemplatingEngineFn
  | false
\`\`\`
Default: `'eta'`.

### `TemplatingEngineName` Templating engine name

```ts
type TemplatingEngineName = 'eta' | 'ejs' | 'handlebars' | 'nunjucks' | 'pug' | 'twig';
\`\`\`

The preprocessor is ready to use the most popular templating engines: Eta, EJS, Handlebars, Nunjucks, Pug, Twig.

### `TemplatingEngineFn` Custom templating engine

```ts
type TemplatingEngineFn = (
  content: string,
  loaderContext: LoaderContext<object> & { data: { [key: string]: any } | string }
) => string | Promise<any> | undefined;
\`\`\`

The function arguments:

- `content` A raw content of a template file defined in [`entry`](entry#entry-entry-points) option.
- `loaderContext` [Loader Context][webpack-loader-context-url] object:
  - `mode: 'production' | 'development' | 'none'` [Webpack mode][webpack-mode-url]
  - `rootContext: string` A path to Webpack context
  - `resource: string` A template file, including query
  - `resourcePath: string` A template file
  - `data: object | null` Data object passed
    in [`entry.entrydescription.data`](entry#entrydescriptiondata) and [`loader.data`](#loader-option-data)

### `false` Disable templating engine

You can use this plugin to resolve all source asset files in any `HTML`-like template used by server-side rendering.
In this case, disable the preprocessor. The plugin resolves all source files and replaces them with the output filenames.
The original template remains unchanged except for the filenames being replaced.

Goals:

1. Quick navigation using headings.
2. Cleaner documentation.
3. Cleaner types

[webdiscus]

Yes, the Preprocessor type can be split into simple types:

• TemplatingEngineName
• PreprocessorFn

[vralle]

data as JSON file

When the data is a string, it must be an absolute or relative path to a file. The file can be a JSON file or a JS file that exports the data as an object. Use the data as a file if you want to get dynamic data in a template. The data file will be reloaded after changes, without restarting Webpack.

I'm a little stuck on this paragraph. My current thoughts are that dynamic data reloading followed by compilation is valid for development mode or watch. Will this work if some server is using Webpack as a middleware?

And how does this behavior depend on the "watch" options?

[webdiscus]

My current thoughts are that dynamic data reloading followed by compilation is valid for development mode.

is meant for dev mode by webpack serv or watch.

[vralle]

Readme.md:

The default preprocessor is pre-configured as the following function:

const { Eta } = require('eta');
const eta = new Eta({
  async: false, // defaults is false, when is true then must be used `await includeAsync()`
  useWith: true, // allow to use variables in template without `it.` scope
  views: process.cwd(), // directory that contains templates
});
preprocessor = (content, { data }) => eta.renderString(content, data);

Another part:

Options for preprocessor: 'eta' (default)

{
  preprocessor: 'eta',
  preprocessorOptions: {
    async: false, // defaults 'false', when is 'true' then must be used `await includeAsync()`
    useWith: true, // defaults 'true', use variables in template without `it.` scope
    views: 'src/views', // relative path to directory that contains templates
    // views: path.join(__dirname, 'src/views'), // absolute path to directory that contains templates
  },
},

The documentation has two versions of the default value for views property. Which value is correct?

[vralle]

I found that:

webdiscus/html-bundler-webpack-plugin/blob/e023d7001ca74acfcb3a7605173bc0e9b6d2df3b/src/Loader/Preprocessors/Eta/index.js#L31C3-L35C4

[webdiscus]

views defaults is webpack root context path: https://webpack.js.org/api/loaders/#thisrootcontext, that defaults is https://webpack.js.org/configuration/entry-context/#context (process.cwd())

[webdiscus]

Another part:

This is just an example, not default values.

[webdiscus]

@vralle

Since we're creating new documentation, now is a good time to do it right.

The plugin documentation is too big and requires good navigation between the different sections, which should always be in the visible area (top/left/right).

FYI, I'm currently working on new docs using docusaurus. I split the readme into smaller parts and created a new document structure. Ready - 75%.

You can later "merge" your changes into new version, since I use *.md and *.mdx files.

[vralle]

views defaults is webpack root context path

There's ambiguous behavior

if (!views) {
    views = rootContext;
  } else if (!path.isAbsolute(views)) {
    views = path.join(rootContext, views);
  }

What does it mean if the root path is not absolute (invalid?), views will lead to ?. Correct me.