rust-lang / rust-lang/mdBook

Consistent output destination directory structure

Open
#3,030 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

Currently if you use single renderer or multiple renderer the structure of the destination directory changes.

If you have a single renderer the output goes directly into the destination directory.

If you have multiple renderers a top level directory is created for each renderer.

This behavior makes it difficult to maintain and optional renderers.

The following creates DEST/index.html:

[output.html]

The following creates DEST/html/index.html:

[output.html]
[output.pdf]
Proposed Solution

I suggest to support additional configuraiton in the output, in this case dest to enable the user to specify where to put the files, keeping backward compatibility when empty and there are more than one is to put render name.

[output.html]
dest=html
Notes

Workaround, always specify both, when we need only html, set pdf command to true.

[output.html]
[output.pdf]
command = true

This is ugly...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing how the output.html and output.pdf configuration is parsed and how renderer destination paths are chosen for single versus multiple renderers. Add support for an optional dest setting while preserving the current default behavior, then verify that the examples produce the requested directory structure.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.