Single page support

[budziq]

Hi,

It would be great to have support for single page rendering and serving.
For instance if I'd like to prepare a nice CONTRIBUTING.md or README.md for my project locally.

From the user perspective all the mdbook commands would work identically as if the [dir] were given but the target path would be a single Markdown file.

I do not know yet how much work would it take (most likely mdbook is quite coupled to the book/chapters idea) but I would be willing to work on it if there is interest in such feature and someone to give some guidance around the codebase ;)

[azerupi]

I have heard this desire from at least one other person and even though I have personally no use for it at the moment, it would certainly be a nice addition.

But before you dive in, I think it would be interesting to first think about what is needed and how it would look like. Write down a very informal idea with some requirements and expectations. With that we will have a better view of how it can be best implemented and what we would need to change in the current design.

For example, for a single markdown page I suppose you would drop the sidebar? What if the user supplies a list of markdown files? Would the sidebar reappear and in what order would the files be displayed? Would we look for a configuration file beside the file or would we just take a default?
Giving an answer to such questions will help us make a plan for the implementation :)

someone to give some guidance around the codebase

I am happy to help, don't hesitate to ask any question you have. Unfortunately it's that time of the year and I am supposed to study for my exams, so I might not always answer immediately. But I will do my best 😉

[budziq]

Write down a very informal idea with some requirements and expectations.

Definitely will do! I'll write something constructive later today when I'm not on mobile 😃

[budziq]

1. My original idea

mdbook serve [FLAGS] [OPTIONS] [dir|file]

Allow user to specify optional [file] instead of [dir] for serve and build subcommands (not sure about test yet). [file] and [dir] would be mutually exclusive.

• generate a single rendered page from specified file (and serve it)
• without sidebar
• config would not be mandatory (load defaults) but used if already present.

2. Your idea with multiple files

mdbook serve [FLAGS] [OPTIONS] [dir| [file..]]

This would be an interesting extension but outside of the scope of what I need ATM
Allow user to specify optional [[file]..] list instead of [dir] for serve and build

• Generate a book exactly as if SUMMARY.md would be filled with contents of [[file]..] list (all on root level).
• sidebar would appear only if there is more than one page
• title and sidebar entries would be filled with text from the first heading for given file (or filename if no heading present)
• config file would not be mandatory (load defaults) but used if already present.

3. Initial ideas for implementation

• update cli commands in mdbook.rs for [dir] to support filenames
• rewrite / split book::init to understand that we might work in "file list mode"
  • possibly create two distinct constructors for book. book::new_from_dir book::new_from_files
  • possibly move book::init into one of the book constructors. Does it make sense as a stand alone method?
  • run parse_summary only in the [dir] mode
• split parse::construct_bookitems into two variants parse::bookitems_from_summary parse::bookitems_from_listor just allow for adding these by hand with filenames
• add BookItems from filenames

Rest of the flow should be similar. Does it make sense?

@azerupi Thanks for your time and good luck on the exams 👍

[budziq]

And don't wory about timing of your responses, there is no real urgency except or lack of something fun to tinker on 😄. I really appreciate your help.

[azerupi]

Very nice write up, thanks!

Point 1. and 2. sound good, nothing to say about that :)

rewrite / split book::init to understand that we might work in "file list mode"

I don't think an init phase is necessary for files. If the file does not exists, we error and exit.

possibly move book::init into one of the book constructors. Does it make sense as a stand alone method?

I think that, in the long run, it would be better to provide more elementary methods like 'create config', 'create summary', ... And then actually implementing the init procedure in the CLI

possibly create two distinct constructors for book. book::new_from_dir book::new_from_files

I would use an empty / default constructor book::new and have builder methods to add files etc.

let mut book = MDBook::new()
book.add_chapter(...)

Anyways, it looks very sound in general :)

When you begin, I recommend that you make several scope-limited PRs as you go. For example, if you need to refactor some parts, make a separate PR. This will make it easier to review for me / us and allows us to give you some feedback about the direction you are going before you are too far along :)

[budziq]

Thanks for your time. I'll try to carve out some free time to work on it this week and send some minimal PR's for review :)

[heyakyra]

Maybe this should be renamed Single-File Input Mode? I just filed a separate ticket for a single page mode (as in rendered as a single page application) #982 so not sure the best way to distinguish these two

[heyakyra]

I have tried several ways to workaround this. A single introduction file doesn't allow the sidebar to be populated with links to the heading anchors.

both of these SUMMARY.md attempts simply break the build step (not surprising, just wish there was a reasonable workaround in the meantime)

# Table of Contents

- [Introduction](./Introduction.md)
- [Heading1](#heading1)
- [Heading2](#heading2)
- [Heading3](#heading3)

# Table of Contents

- [Introduction](./Introduction.md)
- [Heading1](./Introduction.md#heading1)
- [Heading2](./Introduction.md#heading2)
- [Heading3](./Introduction.md#heading3)

[Dylan-DPC-zz]

Closing this since we can carry on the discussion on the new issue. Thanks