Building output not working

[mauriziopassariello]

Hi all,
I am new to Manubot. I have successfully run the script on terminal and cloned the Manubot repository. However when I change the abstract.md file or the deleteme.md file I cannot find any output file in the output folder. What am I doing wrong? Anyone able to help me? Thanks!

[dhimmel]

The rendered manuscript gets created in the output directory only after you run bash build/build.sh. The output folder is useful when building the manuscript locally.

But many users build the manuscript via CI only (on GitHub actions).

It's easier for us to help manuscripts that are public repos. If you have a public repo you can point us towards that can help.

[mauriziopassariello]

Thank you Daniel,
I have made my repository "Manuscript 2" public so that you can have a look.
I am actually not interested to have a local output folder and I am happy to run it on GitHub only. How do I do that?
How do you create a TOC?

Forgive my ignorance but I am already very proud I got to this point...any help is much appreciated!
Take care,

Maurizio

[dhimmel]

Okay so the manuscript is https://github.com/mauriziopassariello/Manuscript2.

It looks like your manuscript is building correctly on CI (logs).

But for some reason GitHub Pages isn't working at https://mauriziopassariello.github.io/Manuscript2/. Can you go to the repo settings and make sure GitHub Pages is configured to use the gh-pages branch? And if you could take a screenshot of the current GitHub Pages settings before changing them, that would be helpful for us.

How do you create a TOC?

The web version has an interactive table of contents that is generated with a javascript plugin. If you also want to include one in non-HTML outputs, the Pandoc --table-of-contents option might help.

[mauriziopassariello]

I have updated the settings.
From this:

To this:

Is that correct? I'm still not able to see changes in the output folder (both on github and local).

[agitter]

That worked to enable GitHub pages. You can now view your manuscript at https://mauriziopassariello.github.io/Manuscript2/

You do not need to use the output directory. If you are curious about what is there, you can view it as a separate branch in your repository at https://github.com/mauriziopassariello/Manuscript2/tree/output. You won't need to visit it because you can access the HTML output from https://mauriziopassariello.github.io/Manuscript2/ and the PDF output from https://mauriziopassariello.github.io/Manuscript2/manuscript.pdf

Your manuscript is not including the content from Paper.md yet. All .md files in the content directory have to start with a number, preferably a two digit number, so they can be placed in the correct order. If you rename this file to 02.Paper.md the content should appear. Note also that you do not need to write the title in that file. The title, authors, and other information are read from metadata.yaml.

@dhimmel based on the "before" screenshot, we may need to update the setup instructions to make enabling GitHub Pages a necessary step by default.

[mauriziopassariello]

Thank you for your help! I'm slowly understanding step by step. Just a few more questions:

1. Where can I find those links in the repository (https://mauriziopassariello.github.io/Manuscript2/)?
2. When do the changes I made in the .md files become "active" in a rendered document? Do I have to make a pull request and merge? I seem to notice that it doesn't happen immediately if I commit. Can you clarify this?

[agitter]

1. Your GitHub repository is https://github.com/mauriziopassariello/Manuscript2 That contains all of your content that will be converted into HTML and a PDF as well as Manubot files needed to do that conversion. The blue buttons at the top of the readme are links to the HTML and PDF versions of your manuscript
   
2. It takes a few minutes, tens of minutes for large documents, for the changes you commit to appear in the HTML of PDF manuscript. Every time your commit, an automated process begins. That runs Manubot to regenerate the HTML and PDF. You can check on the status by clicking the icon next to the most recent commit summary.
   
   Currently the icon is yellow, which means the build process is still running. A green check means the update is done and the HTML and PDF have been updated. A red x means the build failed. If you click these icons, the details link will show you the build logs. You don't need to make a pull request if you are working alone. Once you are working with collaborators, pull requests are useful so everyone can review and discuss changes. After a pull request is merged, it will make a commit to the "main" branch, which will update the HTML and PDF.

[mauriziopassariello]

This is super cool. Thank you!

[mauriziopassariello]

I discovered that the Github pages in the settings can be modified only if the repository is public. Am I right? So there is no way to use Manubot on a private repository?

[dhimmel]

According to https://stackoverflow.com/a/28745353/4651668, you'll need have GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server to use GitHub Pages on a private repository. If you're affiliated with an academic institution, you might qualify for a Pro account through https://education.github.com/.

Note that you can still use manubot on the private repo, just that the manuscript won't be publicly hosted. It can still be downloaded from the output and gh-pages branches.

[mauriziopassariello]

Cloning the manubot/rootstock repository via the setup script creates a local copy on my PC. Is this always required? Can the rootstock repository be cloned/copied only on Github?

[dhimmel]

The local setup is currently required to properly configure the new manuscript. Once setup has occurred, everything else can continue via GitHub only