-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Single page support #301
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
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?
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 😉 |
Definitely will do! I'll write something constructive later today when I'm not on mobile 😃 |
1. My original idea
Allow user to specify optional [file] instead of [dir] for
2. Your idea with multiple files
This would be an interesting extension but outside of the scope of what I need ATM
3. Initial ideas for implementation
Rest of the flow should be similar. Does it make sense? @azerupi Thanks for your time and good luck on the exams 👍 |
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. |
Very nice write up, thanks! Point 1. and 2. sound good, nothing to say about that :)
I don't think an init phase is necessary for files. If the file does not exists, we error and exit.
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
I would use an empty / default constructor 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 :) |
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 :) |
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 |
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
|
Closing this since we can carry on the discussion on the new issue. Thanks |
@Dylan-DPC no it's two different things. Please don't close. SPAs are a js heavy application coding pattern while this issue concerns having writing to a single html file, optimally without any js involved needing to view it. I dislike the way the books are structured that there is forced interactivity. You have to click these buttons instead of just being able to scroll down the page. It makes quickly skimming what you want to find really hard. See also @bluss's opinion on this here. |
Ok I've agreed with @Dylan-DPC (who still seems to be a bit confused) to open a new issue here: #988 |
I'm not confused now :P but still prefer a new issue so that we don't notify everyone here and also so that we don't overlook it (because we rarely check old issues at the moment). Sorry for the trouble and thanks! |
For those of you who still want a single-page input, you can use this bash script I wrote. It takes three parameters: <FILEPATH>, <TITLE>, and optionally [OUTPUT-DIR]. It will quickly spin up a boilerplate Installation
Example usage This will output a directory SCRIPT: #!/bin/bash
USAGE='USAGE: mdbook-oneoff <FILEPATH> <TITLE> [OUTPUT-DIR]'
# Check that two parameters were supplied
[ -z "$2" ] && echo $USAGE && exit 1
TITLE=$2
# Check that <FILE> is a file
[ ! -f "$1" ] && echo $USAGE && exit 2
FILEPATH=$1
# Check that staging directory does not already exist
STAGING_DIR='./__mdbook-oneoff-delete-me__'
[ -d $STAGING_DIR ] && echo 'Please rmdir $STAGING_DIR' && exit 3
# Assign output_dir variable
OUTPUT_DIR=$3
# If no parameter was supplied, use the default
[ -z $3 ] && OUTPUT_DIR='mdbook-oneoff-build'
mkdir $STAGING_DIR
cd $STAGING_DIR
# Init and clean up mdbook directory
mdbook init --force --ignore none
rm src/*
rmdir book
# Copy FILE into mdbook dir
cp ../$FILEPATH ./src
FILE=$(ls ./src)
# Set up SUMMARY and book.toml
printf '# SUMMARY\n' > ./src/SUMMARY.md
printf '[%s](%s)' "$TITLE" $FILE >> ./src/SUMMARY.md
printf '\ntitle = "%s"' "$TITLE" >> ./book.toml
# Build and clean up
mdbook build -d ../$OUTPUT_DIR
rm src/*
rmdir src
rm book.toml
cd ..
rmdir $STAGING_DIR EDIT: You can use monolith ( Example mdbook-oneoff ./README.md 'Test Readme' ./mdbook-oneoff-build
monolith ./mdbook-oneoff-build/index.html > README.html This will convert a plain README.md into a beautiful, mdbook-rendered static HTML file at README.html. |
Uh oh!
There was an error while loading. Please reload this page.
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 ;)
The text was updated successfully, but these errors were encountered: