Skip to content
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

Building output not working #422

Open
mauriziopassariello opened this issue Apr 1, 2021 · 12 comments
Open

Building output not working #422

mauriziopassariello opened this issue Apr 1, 2021 · 12 comments

Comments

@mauriziopassariello
Copy link

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
Copy link
Member

dhimmel commented Apr 2, 2021

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
Copy link
Author

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
Copy link
Member

dhimmel commented Apr 2, 2021

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
Copy link
Author

I have updated the settings.
From this:
Screenshot 2021-04-02 at 13 50 35

To this:
Screenshot 2021-04-02 at 13 51 25

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

@agitter
Copy link
Member

agitter commented Apr 2, 2021

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
Copy link
Author

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
Copy link
Member

agitter commented Apr 2, 2021

  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
    image
  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.
    image
    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
Copy link
Author

This is super cool. Thank you!

@mauriziopassariello
Copy link
Author

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?
Screenshot 2021-04-02 at 20 06 33

@dhimmel
Copy link
Member

dhimmel commented Apr 2, 2021

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
Copy link
Author

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
Copy link
Member

dhimmel commented Apr 3, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants