├── .appveyor.yml ├── .github └── workflows │ ├── ai-revision.yaml │ └── manubot.yaml ├── .gitignore ├── LICENSE-CC0.md ├── LICENSE.md ├── README.md ├── SETUP.md ├── USAGE.md ├── build ├── README.md ├── assets │ ├── custom-dictionary.txt │ └── style.csl ├── autobuild.sh ├── build.sh ├── environment.yml ├── pandoc │ └── defaults │ │ ├── common.yaml │ │ ├── docx.yaml │ │ ├── html.yaml │ │ ├── latex.yaml │ │ └── pdf-weasyprint.yaml ├── plugins │ ├── accordion.html │ ├── analytics.html │ ├── anchors.html │ ├── attributes.html │ ├── core.html │ ├── d3.html │ ├── hypothesis.html │ ├── inline-svg.html │ ├── jump-to-first.html │ ├── lightbox.html │ ├── link-highlight.html │ ├── mathjax.html │ ├── scite.html │ ├── table-of-contents.html │ └── tooltips.html └── themes │ ├── default.docx │ ├── default.html │ └── nih-grant.docx ├── ci ├── .gitignore ├── README.md ├── ai-revision-config.yaml ├── ai-revision-prompts.yaml ├── deploy.sh ├── install-spellcheck.sh └── install.sh ├── content ├── 00.front-matter.md ├── 01.abstract.md ├── 02.delete-me.md ├── 90.back-matter.md ├── images │ ├── github.svg │ ├── mastodon.svg │ ├── orcid.svg │ └── twitter.svg ├── manual-references.json └── metadata.yaml ├── output └── README.md ├── setup.bash └── webpage ├── README.md ├── images ├── index.html └── manuscript.pdf /.appveyor.yml: -------------------------------------------------------------------------------- 1 | # See https://www.appveyor.com/docs/getting-started-with-appveyor-for-linux/ 2 | # Don't build branches with a PR, since their build will be created with the PR itself. 3 | # Otherwise there would be two builds -- one for the PR and one for the branch. 4 | # If you're having issues with getting your PR to build, make sure there are no merge conflicts. 5 | skip_branch_with_pr: true 6 | 7 | # Enable 'Do not build on "Push" events' in the AppVeyor project settings 8 | # to only build commits from pull requests 9 | branches: 10 | only: 11 | - main 12 | - master 13 | 14 | # Only run AppVeyor on commits that modify at least one of the following files 15 | # Delete these lines to run AppVeyor on all main/master branch commits 16 | only_commits: 17 | files: 18 | - .appveyor.yml 19 | - build/ 20 | - ci/install.sh 21 | - content/ 22 | 23 | image: ubuntu2204 24 | services: 25 | - docker 26 | 27 | # Set SPELLCHECK to true to enable Pandoc spellchecking 28 | environment: 29 | SPELLCHECK: true 30 | 31 | install: 32 | # Create the message with the triggering commit before install so it is 33 | # available if the build fails 34 | - TRIGGERING_COMMIT=${APPVEYOR_PULL_REQUEST_HEAD_COMMIT:-APPVEYOR_REPO_COMMIT} 35 | - JOB_MESSAGE=" for commit $TRIGGERING_COMMIT " 36 | - source ci/install.sh 37 | 38 | test_script: 39 | - bash build/build.sh 40 | - MANUSCRIPT_FILENAME=manuscript-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7} 41 | - cp output/manuscript.html $MANUSCRIPT_FILENAME.html 42 | - cp output/manuscript.pdf $MANUSCRIPT_FILENAME.pdf 43 | - appveyor PushArtifact $MANUSCRIPT_FILENAME.html 44 | - appveyor PushArtifact $MANUSCRIPT_FILENAME.pdf 45 | - | 46 | if [ "${SPELLCHECK:-}" = "true" ]; then 47 | SPELLING_ERRORS_FILENAME=spelling-errors-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}.txt 48 | cp output/spelling-errors.txt $SPELLING_ERRORS_FILENAME 49 | appveyor PushArtifact $SPELLING_ERRORS_FILENAME 50 | SPELLING_ERROR_LOCATIONS_FILENAME=spelling-error-locations-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}.txt 51 | cp output/spelling-error-locations.txt $SPELLING_ERROR_LOCATIONS_FILENAME 52 | appveyor PushArtifact $SPELLING_ERROR_LOCATIONS_FILENAME 53 | fi 54 | 55 | build: off 56 | 57 | cache: 58 | - ci/cache 59 | 60 | on_success: 61 | - echo "Artifacts available from $APPVEYOR_URL/project/$APPVEYOR_ACCOUNT_NAME/$APPVEYOR_PROJECT_SLUG/builds/$APPVEYOR_BUILD_ID/artifacts" 62 | - echo "Updated PDF available from $APPVEYOR_URL/api/buildjobs/$APPVEYOR_JOB_ID/artifacts/$MANUSCRIPT_FILENAME.pdf" 63 | - appveyor AddMessage "$JOB_MESSAGE is now complete." 64 | - | 65 | if [ "${SPELLCHECK:-}" = "true" ]; then 66 | SPELLING_ERROR_COUNT=($(wc -l $SPELLING_ERROR_LOCATIONS_FILENAME)) 67 | appveyor AddMessage "
Found $SPELLING_ERROR_COUNT potential spelling error(s). Preview:$(head -n 100 $SPELLING_ERROR_LOCATIONS_FILENAME)" 68 | appveyor AddMessage "...
" 69 | fi 70 | 71 | on_failure: 72 | - appveyor AddMessage "$JOB_MESSAGE failed." 73 | 74 | # The following lines can be safely deleted, which will disable AppVeyorBot 75 | # notifications in GitHub pull requests 76 | # Notifications use Mustache templates http://mustache.github.io/mustache.5.html 77 | # See https://www.appveyor.com/docs/notifications/#customizing-message-template 78 | # for available variables 79 | notifications: 80 | - provider: GitHubPullRequest 81 | template: "AppVeyor [build {{buildVersion}}]({{buildUrl}}) 82 | {{#jobs}}{{#messages}}{{{message}}}{{/messages}}{{/jobs}} 83 | {{#passed}}The rendered manuscript from this build is temporarily available for download at:\n\n 84 | {{#jobs}}{{#artifacts}}- [`{{fileName}}`]({{permalink}})\n{{/artifacts}}{{/jobs}}{{/passed}}" 85 | -------------------------------------------------------------------------------- /.github/workflows/ai-revision.yaml: -------------------------------------------------------------------------------- 1 | name: ai-revision 2 | on: 3 | workflow_dispatch: 4 | inputs: 5 | branch: 6 | description: 'Branch to revise' 7 | required: true 8 | type: string 9 | default: 'main' 10 | file_names: 11 | description: 'File names to revise' 12 | required: false 13 | type: string 14 | default: '' 15 | model: 16 | description: 'Language model' 17 | required: true 18 | type: string 19 | default: 'gpt-4-turbo' 20 | custom_prompt: 21 | description: 'Custom prompt' 22 | required: false 23 | type: string 24 | default: '' 25 | branch_name: 26 | description: 'Output branch' 27 | required: true 28 | type: string 29 | default: 'ai-revision-gpt4turbo' 30 | 31 | jobs: 32 | ai-revise: 33 | name: AI Revise 34 | runs-on: ubuntu-latest 35 | permissions: 36 | contents: write 37 | pull-requests: write 38 | defaults: 39 | run: 40 | shell: bash --login {0} 41 | steps: 42 | - name: Checkout Repo 43 | uses: actions/checkout@v4 44 | with: 45 | ref: ${{ inputs.branch }} 46 | - name: Install environment 47 | uses: actions/setup-python@v5 48 | with: 49 | python-version: '3.11' 50 | - name: Install Manubot AI revision dependencies 51 | run: | 52 | # install using the same URL used for manubot in build/environment.yml 53 | manubot_line=$(grep "github.com/manubot/manubot" build/environment.yml) 54 | manubot_url=$(echo "$manubot_line" | awk -F"- " '{print $2}') 55 | 56 | pip install ${manubot_url}#egg=manubot[ai-rev] 57 | - name: Revise manuscript 58 | env: 59 | OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} 60 | AI_EDITOR_LANGUAGE_MODEL: ${{ inputs.model }} 61 | AI_EDITOR_FILENAMES_TO_REVISE: ${{ inputs.file_names }} 62 | AI_EDITOR_CUSTOM_PROMPT: ${{ inputs.custom_prompt }} 63 | # More variables can be specified to control the behavior of the model: 64 | # https://github.com/manubot/manubot-ai-editor/blob/main/libs/manubot_ai_editor/env_vars.py 65 | run: manubot ai-revision --content-directory content/ --config-directory ci/ 66 | - name: Create Pull Request 67 | uses: peter-evans/create-pull-request@v6 68 | with: 69 | commit-message: 'revise using AI model\n\nUsing the OpenAI model ${{ inputs.model }}' 70 | title: 'AI-based revision using ${{ inputs.model }}' 71 | author: OpenAI model ${{ inputs.model }} 72 | add-paths: | 73 | content/*.md 74 | branch: ${{ inputs.branch_name }} 75 | draft: true 76 | -------------------------------------------------------------------------------- /.github/workflows/manubot.yaml: -------------------------------------------------------------------------------- 1 | name: Manubot 2 | on: 3 | push: 4 | branches: 5 | - main 6 | - master 7 | pull_request: 8 | branches: 9 | - main 10 | - master 11 | # NOTE: scheduled workflows are supported as of 2022-09-27 (example commented below) 12 | # https://github.com/community/community/discussions/12269#discussioncomment-3747667 13 | # scheduled: 14 | # - cron: '40 10 1 * *' # https://crontab.guru/#40_10_1_*_* 15 | workflow_dispatch: 16 | inputs: 17 | BUILD_PDF: 18 | type: boolean 19 | description: generate PDF output 20 | default: true 21 | BUILD_DOCX: 22 | type: boolean 23 | description: generate DOCX output 24 | default: false 25 | BUILD_LATEX: 26 | type: boolean 27 | description: generate LaTeX output 28 | default: false 29 | SPELLCHECK: 30 | type: boolean 31 | description: Check spelling 32 | default: true 33 | MANUBOT_USE_DOCKER: 34 | type: boolean 35 | description: Use Docker to generate PDF 36 | default: true 37 | jobs: 38 | manubot: 39 | name: Manubot 40 | runs-on: ubuntu-latest 41 | permissions: 42 | contents: write 43 | env: 44 | GITHUB_PULL_REQUEST_SHA: ${{ github.event.pull_request.head.sha }} 45 | # Set SPELLCHECK to true/false for whether to check spelling in this action. 46 | # For workflow dispatch jobs, this SPELLCHECK setting will be overridden by the user input. 47 | SPELLCHECK: true 48 | defaults: 49 | run: 50 | shell: bash --login {0} 51 | steps: 52 | - name: Checkout Repository 53 | uses: actions/checkout@v4 54 | with: 55 | # fetch entire commit history to support get_rootstock_commit 56 | fetch-depth: 0 57 | - name: Set Environment Variables (Workflow Dispatch) 58 | if: github.event_name == 'workflow_dispatch' 59 | run: | 60 | echo "BUILD_PDF=${{ github.event.inputs.BUILD_PDF }}" >> $GITHUB_ENV 61 | echo "BUILD_DOCX=${{ github.event.inputs.BUILD_DOCX }}" >> $GITHUB_ENV 62 | echo "BUILD_LATEX=${{ github.event.inputs.BUILD_LATEX }}" >> $GITHUB_ENV 63 | echo "SPELLCHECK=${{ github.event.inputs.SPELLCHECK }}" >> $GITHUB_ENV 64 | echo "MANUBOT_USE_DOCKER=${{ github.event.inputs.MANUBOT_USE_DOCKER }}" >> $GITHUB_ENV 65 | - name: Set Environment Variables 66 | run: | 67 | TRIGGERING_SHA=${GITHUB_PULL_REQUEST_SHA:-$GITHUB_SHA} 68 | echo "TRIGGERING_SHA_7=${TRIGGERING_SHA::7}" >> $GITHUB_ENV 69 | echo "TRIGGERING_SHA: $TRIGGERING_SHA" 70 | DEFAULT_BRANCH=${{ github.event.repository.default_branch }} 71 | echo "DEFAULT_BRANCH=${DEFAULT_BRANCH}" >> $GITHUB_ENV 72 | echo "DEFAULT_BRANCH_REF=refs/heads/$DEFAULT_BRANCH" >> $GITHUB_ENV 73 | echo "DEFAULT_BRANCH=$DEFAULT_BRANCH" 74 | - name: Cache 75 | uses: actions/cache@v4 76 | with: 77 | path: ci/cache 78 | key: ci-cache-${{ github.ref }} 79 | restore-keys: | 80 | ci-cache-${{ env.DEFAULT_BRANCH_REF }} 81 | - name: Install Environment 82 | uses: conda-incubator/setup-miniconda@v3 83 | with: 84 | activate-environment: manubot 85 | environment-file: build/environment.yml 86 | auto-activate-base: false 87 | - name: Install Spellcheck 88 | if: env.SPELLCHECK == 'true' 89 | run: bash ci/install-spellcheck.sh 90 | - name: Build Manuscript 91 | run: bash build/build.sh 92 | - name: Upload Artifacts 93 | uses: actions/upload-artifact@v4 94 | with: 95 | name: manuscript-${{ github.run_id }}-${{ env.TRIGGERING_SHA_7 }} 96 | path: output 97 | - name: Deploy Manuscript 98 | if: github.ref == env.DEFAULT_BRANCH_REF && github.event_name != 'pull_request' && !github.event.repository.fork 99 | env: 100 | MANUBOT_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} 101 | MANUBOT_SSH_PRIVATE_KEY: ${{ secrets.MANUBOT_SSH_PRIVATE_KEY }} 102 | CI_BUILD_WEB_URL: https://github.com/${{ github.repository }}/commit/${{ github.sha }}/checks 103 | CI_JOB_WEB_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} 104 | run: bash ci/deploy.sh 105 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Generated manuscript output files 2 | output/* 3 | !output/README.md 4 | 5 | webpage/v 6 | 7 | # When PDF building fails, a temporary symlink named images in the root 8 | # directory is not removed. 9 | /images 10 | 11 | # Manubot cache directory 12 | ci/cache 13 | 14 | # Pandoc filters downloaded during continuous integration setup 15 | build/pandoc/filters/spellcheck.lua 16 | 17 | # Python 18 | __pycache__/ 19 | *.pyc 20 | 21 | # Jupyter Notebook 22 | .ipynb_checkpoints 23 | 24 | # Misc temporary files 25 | *.bak 26 | 27 | # System specific files 28 | 29 | ## Linux 30 | *~ 31 | .Trash-* 32 | 33 | ## macOS 34 | .DS_Store 35 | ._* 36 | .Trashes 37 | 38 | ## Windows 39 | Thumbs.db 40 | [Dd]esktop.ini 41 | 42 | ## Text Editors 43 | .vscode 44 | -------------------------------------------------------------------------------- /LICENSE-CC0.md: -------------------------------------------------------------------------------- 1 | # CC0 1.0 Universal 2 | 3 | ``` 4 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER. 5 | ``` 6 | 7 | ### Statement of Purpose 8 | 9 | The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work"). 10 | 11 | Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others. 12 | 13 | For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights. 14 | 15 | 1. __Copyright and Related Rights.__ A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following: 16 | 17 | i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; 18 | 19 | ii. moral rights retained by the original author(s) and/or performer(s); 20 | 21 | iii. publicity and privacy rights pertaining to a person's image or likeness depicted in a Work; 22 | 23 | iv. rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; 24 | 25 | v. rights protecting the extraction, dissemination, use and reuse of data in a Work; 26 | 27 | vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and 28 | 29 | vii. other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof. 30 | 31 | 2. __Waiver.__ To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose. 32 | 33 | 3. __Public License Fallback.__ Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose. 34 | 35 | 4. __Limitations and Disclaimers.__ 36 | 37 | a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. 38 | 39 | b. Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. 40 | 41 | c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. 42 | 43 | d. Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work. 44 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Creative Commons Attribution 4.0 International 2 | 3 | Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. 4 | 5 | ### Using Creative Commons Public Licenses 6 | 7 | Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. 8 | 9 | * __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). 10 | 11 | * __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). 12 | 13 | ## Creative Commons Attribution 4.0 International Public License 14 | 15 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 16 | 17 | ### Section 1 – Definitions. 18 | 19 | a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 20 | 21 | b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 22 | 23 | c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 24 | 25 | d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 26 | 27 | e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 28 | 29 | f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 30 | 31 | g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 32 | 33 | h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. 34 | 35 | i. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 36 | 37 | j. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 38 | 39 | k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. 40 | 41 | ### Section 2 – Scope. 42 | 43 | a. ___License grant.___ 44 | 45 | 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 46 | 47 | A. reproduce and Share the Licensed Material, in whole or in part; and 48 | 49 | B. produce, reproduce, and Share Adapted Material. 50 | 51 | 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 52 | 53 | 3. __Term.__ The term of this Public License is specified in Section 6(a). 54 | 55 | 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 56 | 57 | 5. __Downstream recipients.__ 58 | 59 | A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 60 | 61 | B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 62 | 63 | 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 64 | 65 | b. ___Other rights.___ 66 | 67 | 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 68 | 69 | 2. Patent and trademark rights are not licensed under this Public License. 70 | 71 | 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 72 | 73 | ### Section 3 – License Conditions. 74 | 75 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 76 | 77 | a. ___Attribution.___ 78 | 79 | 1. If You Share the Licensed Material (including in modified form), You must: 80 | 81 | A. retain the following if it is supplied by the Licensor with the Licensed Material: 82 | 83 | i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 84 | 85 | ii. a copyright notice; 86 | 87 | iii. a notice that refers to this Public License; 88 | 89 | iv. a notice that refers to the disclaimer of warranties; 90 | 91 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 92 | 93 | B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 94 | 95 | C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 96 | 97 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 98 | 99 | 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 100 | 101 | 4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License. 102 | 103 | ### Section 4 – Sui Generis Database Rights. 104 | 105 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 106 | 107 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 108 | 109 | b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and 110 | 111 | c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 112 | 113 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 114 | 115 | ### Section 5 – Disclaimer of Warranties and Limitation of Liability. 116 | 117 | a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ 118 | 119 | b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ 120 | 121 | c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 122 | 123 | ### Section 6 – Term and Termination. 124 | 125 | a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 126 | 127 | b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 128 | 129 | 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 130 | 131 | 2. upon express reinstatement by the Licensor. 132 | 133 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 134 | 135 | c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 136 | 137 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 138 | 139 | ### Section 7 – Other Terms and Conditions. 140 | 141 | a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 142 | 143 | b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. 144 | 145 | ### Section 8 – Interpretation. 146 | 147 | a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 148 | 149 | b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 150 | 151 | c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 152 | 153 | d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 154 | 155 | ``` 156 | Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. 157 | 158 | Creative Commons may be contacted at creativecommons.org 159 | ``` 160 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Automated scholarly manuscripts on GitHub 2 | 3 | 4 | 5 | [![HTML Manuscript](https://img.shields.io/badge/manuscript-HTML-blue.svg)](https://manubot.github.io/rootstock/) 6 | [![PDF Manuscript](https://img.shields.io/badge/manuscript-PDF-blue.svg)](https://manubot.github.io/rootstock/manuscript.pdf) 7 | [![GitHub Actions Status](https://github.com/manubot/rootstock/workflows/Manubot/badge.svg)](https://github.com/manubot/rootstock/actions) 8 | 9 | ## Manuscript description 10 | 11 | 12 | 13 | This repository is a template manuscript (a.k.a. rootstock). 14 | Actual manuscript instances will clone this repository (see [`SETUP.md`](SETUP.md)) and replace this paragraph with a description of their manuscript. 15 | 16 | ## Manubot 17 | 18 | 19 | 20 | Manubot is a system for writing scholarly manuscripts via GitHub. 21 | Manubot automates citations and references, versions manuscripts using git, and enables collaborative writing via GitHub. 22 | An [overview manuscript](https://greenelab.github.io/meta-review/ "Open collaborative writing with Manubot") presents the benefits of collaborative writing with Manubot and its unique features. 23 | The [rootstock repository](https://git.io/fhQH1) is a general purpose template for creating new Manubot instances, as detailed in [`SETUP.md`](SETUP.md). 24 | See [`USAGE.md`](USAGE.md) for documentation how to write a manuscript. 25 | 26 | Please open [an issue](https://git.io/fhQHM) for questions related to Manubot usage, bug reports, or general inquiries. 27 | 28 | ### Repository directories & files 29 | 30 | The directories are as follows: 31 | 32 | + [`content`](content) contains the manuscript source, which includes markdown files as well as inputs for citations and references. 33 | See [`USAGE.md`](USAGE.md) for more information. 34 | + [`output`](output) contains the outputs (generated files) from Manubot including the resulting manuscripts. 35 | You should not edit these files manually, because they will get overwritten. 36 | + [`webpage`](webpage) is a directory meant to be rendered as a static webpage for viewing the HTML manuscript. 37 | + [`build`](build) contains commands and tools for building the manuscript. 38 | + [`ci`](ci) contains files necessary for deployment via continuous integration. 39 | 40 | ### Local execution 41 | 42 | The easiest way to run Manubot is to use [continuous integration](#continuous-integration) to rebuild the manuscript when the content changes. 43 | If you want to build a Manubot manuscript locally, install the [conda](https://conda.io) environment as described in [`build`](build). 44 | Then, you can build the manuscript on POSIX systems by running the following commands from this root directory. 45 | 46 | ```sh 47 | # Activate the manubot conda environment (assumes conda version >= 4.4) 48 | conda activate manubot 49 | 50 | # Build the manuscript, saving outputs to the output directory 51 | bash build/build.sh 52 | 53 | # At this point, the HTML & PDF outputs will have been created. The remaining 54 | # commands are for serving the webpage to view the HTML manuscript locally. 55 | # This is required to view local images in the HTML output. 56 | 57 | # Configure the webpage directory 58 | manubot webpage 59 | 60 | # You can now open the manuscript webpage/index.html in a web browser. 61 | # Alternatively, open a local webserver at http://localhost:8000/ with the 62 | # following commands. 63 | cd webpage 64 | python -m http.server 65 | ``` 66 | 67 | Sometimes it's helpful to monitor the content directory and automatically rebuild the manuscript when a change is detected. 68 | The following command, while running, will trigger both the `build.sh` script and `manubot webpage` command upon content changes: 69 | 70 | ```sh 71 | bash build/autobuild.sh 72 | ``` 73 | 74 | ### Continuous Integration 75 | 76 | Whenever a pull request is opened, CI (continuous integration) will test whether the changes break the build process to generate a formatted manuscript. 77 | The build process aims to detect common errors, such as invalid citations. 78 | If your pull request build fails, see the CI logs for the cause of failure and revise your pull request accordingly. 79 | 80 | When a commit to the `main` branch occurs (for example, when a pull request is merged), CI builds the manuscript and writes the results to the [`gh-pages`](https://github.com/manubot/rootstock/tree/gh-pages) and [`output`](https://github.com/manubot/rootstock/tree/output) branches. 81 | The `gh-pages` branch uses [GitHub Pages](https://pages.github.com/) to host the following URLs: 82 | 83 | + **HTML manuscript** at https://manubot.github.io/rootstock/ 84 | + **PDF manuscript** at https://manubot.github.io/rootstock/manuscript.pdf 85 | 86 | For continuous integration configuration details, see [`.github/workflows/manubot.yaml`](.github/workflows/manubot.yaml). 87 | 88 | ## License 89 | 90 | 94 | 95 | [![License: CC BY 4.0](https://img.shields.io/badge/License%20All-CC%20BY%204.0-lightgrey.svg)](http://creativecommons.org/licenses/by/4.0/) 96 | [![License: CC0 1.0](https://img.shields.io/badge/License%20Parts-CC0%201.0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/) 97 | 98 | Except when noted otherwise, the entirety of this repository is licensed under a CC BY 4.0 License ([`LICENSE.md`](LICENSE.md)), which allows reuse with attribution. 99 | Please attribute by linking to https://github.com/manubot/rootstock. 100 | 101 | Since CC BY is not ideal for code and data, certain repository components are also released under the CC0 1.0 public domain dedication ([`LICENSE-CC0.md`](LICENSE-CC0.md)). 102 | All files matched by the following glob patterns are dual licensed under CC BY 4.0 and CC0 1.0: 103 | 104 | + `*.sh` 105 | + `*.py` 106 | + `*.yml` / `*.yaml` 107 | + `*.json` 108 | + `*.bib` 109 | + `*.tsv` 110 | + `.gitignore` 111 | 112 | All other files are only available under CC BY 4.0, including: 113 | 114 | + `*.md` 115 | + `*.html` 116 | + `*.pdf` 117 | + `*.docx` 118 | 119 | Please open [an issue](https://github.com/manubot/rootstock/issues) for any question related to licensing. 120 | -------------------------------------------------------------------------------- /SETUP.md: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | 3 | - [Creating a new manuscript](#creating-a-new-manuscript) 4 | * [Using setup script](#using-setup-script) 5 | * [Manual configuration](#manual-configuration) 6 | * [Create repository](#create-repository) 7 | * [Continuous integration](#continuous-integration) 8 | + [GitHub Actions](#github-actions) 9 | + [SSH Deploy Key](#ssh-deploy-key) 10 | - [Add the public key to GitHub](#add-the-public-key-to-github) 11 | - [Add the private key to GitHub](#add-the-private-key-to-github) 12 | + [Previewing pull request builds with AppVeyor](#previewing-pull-request-builds-with-appveyor) 13 | * [README updates](#readme-updates) 14 | * [Finalize](#finalize) 15 | - [Merging upstream rootstock changes](#merging-upstream-rootstock-changes) 16 | * [Default branch](#default-branch) 17 | 18 | _generated with [markdown-toc](https://ecotrust-canada.github.io/markdown-toc/)_ 19 | 20 | # Creating a new manuscript 21 | 22 | These instructions detail how to create a new manuscript based off of the [`manubot/rootstock`](https://github.com/manubot/rootstock/) repository. 23 | The process can be a bit challenging, because it requires a few steps that are difficult to automate. 24 | However, you will only have to perform these steps once for each manuscript. 25 | 26 | These steps should be performed in a command-line shell (terminal), starting in the directory where you want the manuscript folder be created. 27 | Setup is supported on Linux, macOS, and Windows. 28 | Windows setup requires [Git Bash](https://gitforwindows.org/) or [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/faq). 29 | 30 | ## Using setup script 31 | Creating a new manuscript using GitHub actions, the recommended default CI service (see below), can be achieved easily using the [setup script](https://github.com/manubot/rootstock/blob/main/setup.bash). 32 | This simply runs the steps detailed below in the manual configuration. 33 | 34 | Use the command below to copy `setup.bash` and run it. 35 | You can check the code that will be executed [here](https://github.com/manubot/rootstock/blob/main/setup.bash). 36 | 37 | ````sh 38 | bash <( curl --location https://github.com/manubot/rootstock/raw/main/setup.bash ) 39 | ```` 40 | The script will then take you through the process of cloning the rootstock repo, make the changes required to use GitHub actions, edit the README to point to your repo and commit the changes. 41 | Your new manuscript repo is then ready for you to start adding your own content. 42 | 43 | This script does not create the remote repo for you, so you will be prompted to manually create an empty GitHub repository at . 44 | Do not initialize the repository, other than optionally adding a description. 45 | 46 | ### CLI 47 | There is also a command line interface for users who want to create manuscripts at scale and in an automated way. 48 | See the help for details. 49 | 50 | ````sh 51 | bash setup.bash --help 52 | ```` 53 | 54 | ## Manual configuration 55 | 56 | If you do not wish to use the above setup script to configure your new manuscript repository, you can instead execute the steps manually. 57 | First, you must configure two environment variables (`OWNER` and `REPO`). 58 | These variables specify the GitHub repository for the manuscript (i.e. `https://github.com/OWNER/REPO`). 59 | Make sure that the case of `OWNER` matches how your username is displayed on GitHub. 60 | In general, assume that all commands in this setup are case-sensitive. 61 | **Edit the following commands with your manuscript's information:** 62 | 63 | ```sh 64 | # GitHub username or organization name (change from manubot) 65 | OWNER=manubot 66 | # Repository name (change from rootstock) 67 | REPO=rootstock 68 | ``` 69 | 70 | ## Create repository 71 | 72 | **Execute the remaining commands verbatim.** 73 | They do not need to be edited (if the setup works as intended). 74 | 75 | Next you must clone `manubot/rootstock` and reconfigure the remote repositories: 76 | 77 | ```sh 78 | # Clone manubot/rootstock 79 | git clone --single-branch https://github.com/manubot/rootstock.git $REPO 80 | cd $REPO 81 | 82 | # Configure remotes 83 | git remote add rootstock https://github.com/manubot/rootstock.git 84 | 85 | # Option A: Set origin URL using its web address 86 | git remote set-url origin https://github.com/$OWNER/$REPO.git 87 | # Option B: If GitHub SSH key access is enabled for OWNER, run the following command instead 88 | git remote set-url origin git@github.com:$OWNER/$REPO.git 89 | ``` 90 | 91 | Then create an empty repository on GitHub. 92 | You can do this at or via the [GitHub command line interface](https://github.com/cli/cli) (if installed) with `gh repo create`. 93 | Make sure to use the same "Owner" and "Repository name" specified above. 94 | Do not initialize the repository, other than optionally adding a Description. 95 | Next, push your cloned manuscript: 96 | 97 | ```sh 98 | git push --set-upstream origin main 99 | ``` 100 | 101 | ## Continuous integration 102 | 103 | Manubot integrates with cloud services to perform continuous integration (CI). 104 | For Manubot that means automatically building and deploying your manuscript. 105 | Manubot supports the following CI services: 106 | 107 | | Service | Default | Artifacts | Deployment | Config | Private Repos | 108 | |---------|---------|-----------|---------|--------|---------------| 109 | | [GitHub Actions](https://github.com/features/actions) | ✔️ | ✔️ | ✔️ | [`manubot.yaml`](.github/workflows/manubot.yaml) | 2,000 minutes per month | 110 | | [AppVeyor](https://www.appveyor.com/) | ❌ | ✔️ with PR comments | ❌ | [`.appveyor.yml`](.appveyor.yml) | 14 day trial | 111 | 112 | Notes on table fields: 113 | 114 | - **Default**: Whether the following uncollapsed setup instructions enable the service by default. 115 | - **Artifacts**: Manuscript outputs that are saved alongside the CI build logs. 116 | This is especially helpful for previewing changes that are under development in a pull request. 117 | Both GitHub Actions and AppVeyor upload the rendered manuscript as an artifact for pull request builds. 118 | However, only AppVeyor comments on pull requests with a download link to the artifacts ([example](https://github.com/manubot/rootstock/pull/262#issuecomment-519944731)). 119 | - **Deployment**: Whether the CI service can write outputs back to the GitHub repository (to the `output` and `gh-pages` branches). 120 | Deployment provides GitHub Pages with the latest manuscript version to serve to the manuscript's URL. 121 | GitHub Actions will deploy by default without any additional setup. 122 | - **Config**: File configuring what operations CI will perform. 123 | Removing this file is one method to disable the CI service. 124 | - **Private Repos**: Quota for private repos. 125 | Only GitHub Actions supports cost-free builds of private repositories beyond a trial period. 126 | All services are cost-free for public repos. 127 | 128 | Manubot was originally designed to use Travis CI, 129 | but later switched to primarily use GitHub Actions. 130 | Support for Travis was [removed](https://github.com/manubot/rootstock/issues/446) in 2021. 131 | 132 | ### GitHub Actions 133 | 134 | GitHub Actions is the recommended default CI service because it requires no additional setup. 135 | To use GitHub Actions only, remove configuration files for other CI services: 136 | 137 | ```shell 138 | # remove AppVeyor config 139 | git rm .appveyor.yml 140 | # remove ci/install.sh (only used by AppVeyor) 141 | git rm ci/install.sh 142 | ``` 143 | 144 | GitHub Actions is _usually_ able to deploy without any additional setup using the [`GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) for authentication. 145 | GitHub Pages deployment using `GITHUB_TOKEN` recently started working on GitHub without an official announcement. 146 | If it does not work for you after completing this setup, try reselecting "gh-pages branch" as the Source for GitHub Pages in the repository Settings. 147 | GitHub Pages should now trigger on the next commit. 148 | If not, [let us know](https://github.com/manubot/rootstock/issues/new). 149 | 150 | For an alternative deployment method on GitHub, 151 | you can use an SSH Deploy Key instead. 152 | However, the setup is more complex. 153 | The following sections, collapsed by default, detail how to generate an SSH Deploy Key. 154 | 155 |
156 | Expand for SSH Deploy Key setup 157 | 158 | ### SSH Deploy Key 159 | 160 | Previously, GitHub Actions required an SSH Deploy Key, 161 | but now GitHub can deploy using the `GITHUB_TOKEN` secret. 162 | Therefore, users following the default configuration can skip these steps. 163 | Otherwise, generate a deploy key so CI can write to the repository. 164 | 165 | ```sh 166 | # Generate deploy.key.pub (public) and deploy.key (private) 167 | ssh-keygen \ 168 | -t rsa -b 4096 -N "" \ 169 | -C "deploy@manubot.org" \ 170 | -f ci/deploy.key 171 | 172 | # Encode deploy.key to remove newlines, writing encoded text to deploy.key.txt. 173 | # This was required for entry into the Travis settings. 174 | openssl base64 -A -in ci/deploy.key > ci/deploy.key.txt 175 | ``` 176 | 177 | #### Add the public key to GitHub 178 | 179 | ```sh 180 | # Print the URL for adding the public key to GitHub 181 | echo "https://github.com/$OWNER/$REPO/settings/keys/new" 182 | 183 | # Print the public key for copy-pasting to GitHub 184 | cat ci/deploy.key.pub 185 | ``` 186 | 187 | Go to the GitHub settings URL echoed above in a browser, and click "Add deploy key". 188 | For "Title", add a description like "Manubot Deploy Key". 189 | Copy-paste the contents of the `ci/deploy.key.pub` text file (printed above by `cat`) into the "Key" text box. 190 | Check the "Allow write access" box below. 191 | Finally, click "Add key". 192 | 193 | #### Add the private key to GitHub 194 | 195 | If you would like GitHub Actions to use SSH for deployment, rather than via HTTPS using `GITHUB_TOKEN`, perform the steps in this section. 196 | 197 | ```sh 198 | # Print the URL for adding the private key to GitHub 199 | echo "https://github.com/$OWNER/$REPO/settings/secrets" 200 | 201 | # Print the encoded private key for copy-pasting to GitHub 202 | cat ci/deploy.key.txt && echo 203 | ``` 204 | 205 | Next, go to the GitHub repository settings page (URL echoed above). 206 | Click "Add a new secret". 207 | For "Name", enter `MANUBOT_SSH_PRIVATE_KEY`. 208 | Next, copy-paste the content of `ci/deploy.key.txt` into "Value" 209 | (printed above by `cat`, including any trailing `=` characters if present). 210 |
211 | 212 | 213 |
214 | Expand for AppVeyor setup 215 | 216 | ### Previewing pull request builds with AppVeyor 217 | 218 | You can optionally enable AppVeyor continuous integration to view pull request builds. 219 | AppVeyor supports storing manuscripts generated during pull request builds as artifacts. 220 | These can be previewed to facilitate pull request review and ensure formatting and reference changes render as expected. 221 | When a pull request build runs successfully, **@AppVeyorBot** will comment on the pull request with a download link to the manuscript PDF. 222 | 223 | To enable AppVeyor, follow steps 1 and 2 of the [AppVeyor welcome](https://www.appveyor.com/docs/) to sign in to AppVeyor and add your manuscript repository as an AppVeyor project. 224 | The repository already contains an `.appveyor.yml` build configuration file, so no other setup is required. 225 | AppVeyor only runs when it detects changes that are likely to affect the manuscript. 226 |
227 | 228 | ## README updates 229 | 230 | The continuous integration configuration should now be complete. 231 | Now update `README.md` files to reference your new repository: 232 | 233 | ```shell 234 | # Perform substitutions 235 | sed "s/manubot\/rootstock/$OWNER\/$REPO/g" README.md > tmp && mv -f tmp README.md 236 | sed "s/manubot\.github\.io\/rootstock/$OWNER\.github\.io\/$REPO/g" README.md > tmp && mv -f tmp README.md 237 | ``` 238 | 239 | ## Finalize 240 | 241 | The `content/02.delete-me.md` file details the Markdown syntax and formatting options available with Manubot. 242 | Remove it to reduce the content to a blank manuscript: 243 | 244 | ```shell 245 | # Remove deletable content file 246 | git rm content/02.delete-me.md 247 | ``` 248 | 249 | Run `git status` or `git diff --color-words` to double check the changes thus far. 250 | If the changes look okay, commit and push: 251 | 252 | ```shell 253 | git add --update 254 | git commit --message "Brand repo to $OWNER/$REPO" 255 | git push origin main 256 | ``` 257 | 258 | You should be good to go now. 259 | A good first step is to modify [`content/metadata.yaml`](content/metadata.yaml) with the relevant information for your manuscript. 260 | 261 | # Merging upstream rootstock changes 262 | 263 | This section will describe how to incorporate changes to rootstock that occurred since initializing your manuscript. 264 | You will want to do this if there are new enhancements or bugfixes that you want to incorporate. 265 | This process can be difficult, especially if conflicts have arisen, and is recommended only for advanced git users. 266 | 267 | It is recommended to do rootstock upgrades via a pull request to help you view the proposed changes and to ensure the build uses the updated environment. 268 | First, checkout a new branch to use as the pull request head branch: 269 | 270 | ```shell 271 | # checkout a new branch, named using the current date, i.e. rootstock-2018-11-16 272 | git checkout -b rootstock-$(date '+%Y-%m-%d') 273 | ``` 274 | 275 | Second, pull the new commits from rootstock, but do not automerge: 276 | 277 | ```shell 278 | # if rootstock remote is not set, add it 279 | git config remote.rootstock.url || git remote add rootstock https://github.com/manubot/rootstock.git 280 | 281 | # pull the new commits from rootstock 282 | git pull --no-ff --no-rebase --no-commit rootstock main 283 | ``` 284 | 285 | If all goes well, there won't be any conflicts. 286 | However, if there are conflicts, follow the suggested commands to resolve them. 287 | 288 | You can add the changes incrementally using `git add --patch`. 289 | This is helpful to see each upstream change. 290 | You may notice changes that affect how items in `content` are processed. 291 | If so, you should edit and stage `content` files as needed. 292 | When there are no longer any unstaged changes, then do `git commit`. 293 | 294 | If updating your default branch (i.e. `main` or `master`) via a pull request, proceed to push the commit to GitHub and open a pull request. 295 | Once the pull request is ready to merge, use GitHub's "Create a merge commit" option rather than "Squash and merge" or "Rebase and merge" to preserve the rootstock commit hashes. 296 | 297 | The environment for local builds does not automatically update when [`build/environment.yml`](build/environment.yml) changes. 298 | To update your local conda `manubot` environment with new changes, run: 299 | 300 | ```shell 301 | # update a local conda environment 302 | conda env update --file build/environment.yml 303 | ``` 304 | 305 | ## Default branch 306 | 307 | On 2020-10-01, GitHub [changed](https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/) the default branch name for new repositories from `master` to `main`. 308 | More information on GitHub's migration is available at [github/renaming](https://github.com/github/renaming). 309 | 310 | On 2020-12-10, Manubot [updated](https://github.com/manubot/rootstock/pull/399) the Rootstock default branch to `main`. 311 | For existing manuscripts, the default branch will remain `master`, 312 | unless manually switched to `main`. 313 | Rootstock has been configured to run continuous integration on both `main` and `master`, 314 | so existing manuscripts can, but are not required, to switch their default branch to `main`. 315 | 316 | Upgrading to the latest Rootstock will change several READMEs links to `main`. 317 | For manuscripts that do not plan to switch their default branch, 318 | do not include these changes in the upgrade merge commit. 319 | -------------------------------------------------------------------------------- /build/README.md: -------------------------------------------------------------------------------- 1 | # Building the manuscript 2 | 3 | [`build.sh`](build.sh) builds the repository. 4 | `bash build/build.sh` should be executed from the root directory of the repository. 5 | By default, `build.sh` creates HTML and PDF outputs. 6 | However, setting the `BUILD_PDF` environment variable to `false` will suppress PDF output. 7 | For example, run local builds using the command `BUILD_PDF=false bash build/build.sh`. 8 | 9 | To build a DOCX file of the manuscript, set the `BUILD_DOCX` environment variable to `true`. 10 | For example, use the command `BUILD_DOCX=true bash build/build.sh` locally. 11 | To export DOCX for all CI builds, set an environment variable in the CI configuration file. 12 | For GitHub Actions, set the variable in `.github\workflows\manubot.yaml` (see [docs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)): 13 | 14 | ```yaml 15 | name: Manubot 16 | env: 17 | BUILD_DOCX: true 18 | ``` 19 | 20 | To generate a single DOCX output of the latest manuscript with GitHub Actions, click the "Actions" tab at the top of the repository. 21 | Select the "Manubot" workflow, then the "Run workflow" button and check "generate DOCX output" before clicking the green "Run workflow" button. 22 | 23 | Currently, equation numbers via `pandoc-eqnos` are not supported for DOCX output. 24 | 25 | Format conversion is done using [Pandoc](https://pandoc.org/MANUAL.html). 26 | `build.sh` calls `pandoc` commands using the options specified in [`pandoc/defaults`](pandoc/defaults). 27 | Each file specifies a set of pandoc `--defaults` options for a given format. 28 | To change the options, either edit the YAML files directly or add additional `--defaults` files. 29 | 30 | ## Environment 31 | 32 | Note: currently, **Windows is not supported**. 33 | 34 | The Manubot environment is managed with [conda](https://conda.io). 35 | If you do not have `conda` installed, we recommend using the Miniforge3 installer from [miniforge](https://github.com/conda-forge/miniforge) (includes `conda` and `mamba`). 36 | Install the environment from [`environment.yml`](environment.yml) by running one of following commands 37 | (from the repository's root directory): 38 | 39 | ```sh 40 | # Install the environment using conda 41 | conda env create --file build/environment.yml 42 | 43 | # Install the environment using mamba (faster) 44 | mamba env create --file build/environment.yml 45 | ``` 46 | 47 | If the `manubot` environment is already installed, but needs to be updated to reflect changes to `environment.yml`, use one of the following options: 48 | 49 | ```shell 50 | # option 1: update the existing environment. 51 | conda env update --file build/environment.yml 52 | 53 | # option 2: remove and reinstall the manubot environment. 54 | # Slower than option 1, but guarantees a fresh environment. 55 | conda env remove --name manubot 56 | conda env create --file build/environment.yml 57 | 58 | # option 3: reinstall the manubot environment faster using mamba. 59 | mamba env create --force --file build/environment.yml 60 | ``` 61 | 62 | Activate with `conda activate manubot` (assumes `conda` version of [at least](https://github.com/conda/conda/blob/9d759d8edeb86569c25f6eb82053f09581013a2a/CHANGELOG.md#440-2017-12-20) 4.4). 63 | The environment should successfully install on both Linux and macOS. 64 | However, it will fail on Windows due to the [`pango`](https://anaconda.org/conda-forge/pango) dependency. 65 | 66 | Because the build process is dependent on having the appropriate version of the `manubot` Python package, 67 | it is necessary to use the version specified in `environment.yml`. 68 | The latest `manubot` release on PyPI may not be compatible with the latest version of this rootstock repository. 69 | 70 | ## Building PDFs 71 | 72 | If Docker is available, `build.sh` uses the [Athena](https://www.athenapdf.com/) [Docker image](https://hub.docker.com/r/arachnysdocker/athenapdf) to build the PDF. 73 | Otherwise, `build.sh` uses [WeasyPrint](https://weasyprint.org/) to build the PDF. 74 | It is common for WeasyPrint to generate many warnings and errors that can be safely ignored. 75 | Examples are shown below: 76 | 77 | ```text 78 | WARNING: Ignored `pointer-events: none` at 3:16, unknown property. 79 | WARNING: Ignored `font-display:auto` at 1:53114, descriptor not supported. 80 | ERROR: Failed to load font at "https://use.fontawesome.com/releases/v5.7.2/webfonts/fa-brands-400.eot#iefix" 81 | WARNING: Expected a media type, got only/**/screen 82 | ``` 83 | -------------------------------------------------------------------------------- /build/assets/custom-dictionary.txt: -------------------------------------------------------------------------------- 1 | personal_ws-1.1 en 22 2 | al 3 | doi 4 | eq 5 | et 6 | github 7 | isbn 8 | latex 9 | manubot 10 | orcid 11 | permalink 12 | pmc 13 | pmcid 14 | pmid 15 | pubmed 16 | rootstock 17 | s 18 | strikethrough 19 | svg 20 | svgs 21 | tbl 22 | unicode 23 | wikidata 24 | -------------------------------------------------------------------------------- /build/assets/style.csl: -------------------------------------------------------------------------------- 1 | 2 | 79 | -------------------------------------------------------------------------------- /build/autobuild.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## autobuild.sh: automatically rebuild mansucript outputs and the webpage when content changes 4 | ## Depends on watchdog https://github.com/gorakhargosh/watchdog 5 | 6 | watchmedo shell-command \ 7 | --wait \ 8 | --command='bash build/build.sh && manubot webpage' \ 9 | content 10 | -------------------------------------------------------------------------------- /build/build.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## build.sh: compile manuscript outputs from content using Manubot and Pandoc 4 | 5 | set -o errexit \ 6 | -o nounset \ 7 | -o pipefail 8 | 9 | # Set timezone used by Python for setting the manuscript's date 10 | export TZ=Etc/UTC 11 | # Default Python to read/write text files using UTF-8 encoding 12 | export LC_ALL=en_US.UTF-8 13 | 14 | 15 | # Set DOCKER_RUNNING to true if docker is running, otherwise false. 16 | DOCKER_RUNNING="$(docker info &> /dev/null && echo "true" || (true && echo "false"))" 17 | 18 | # Set option defaults 19 | CI="${CI:-false}" 20 | BUILD_PDF="${BUILD_PDF:-true}" 21 | BUILD_DOCX="${BUILD_DOCX:-false}" 22 | BUILD_LATEX="${BUILD_LATEX:-false}" 23 | SPELLCHECK="${SPELLCHECK:-false}" 24 | MANUBOT_USE_DOCKER="${MANUBOT_USE_DOCKER:-$DOCKER_RUNNING}" 25 | # Pandoc's configuration is specified via files of option defaults 26 | # located in the $PANDOC_DATA_DIR/defaults directory. 27 | PANDOC_DATA_DIR="${PANDOC_DATA_DIR:-build/pandoc}" 28 | 29 | # Generate reference information 30 | echo >&2 "Retrieving and processing reference metadata" 31 | manubot process \ 32 | --content-directory=content \ 33 | --output-directory=output \ 34 | --cache-directory=ci/cache \ 35 | --skip-citations \ 36 | --log-level=INFO 37 | 38 | # Make output directory 39 | mkdir -p output 40 | 41 | # Create HTML output 42 | # https://pandoc.org/MANUAL.html 43 | echo >&2 "Exporting HTML manuscript" 44 | pandoc --verbose \ 45 | --data-dir="$PANDOC_DATA_DIR" \ 46 | --defaults=common.yaml \ 47 | --defaults=html.yaml 48 | 49 | # Create PDF output (unless BUILD_PDF environment variable equals "false") 50 | # If Docker is not available, use WeasyPrint to create PDF 51 | if [ "${BUILD_PDF}" != "false" ] && [ "${MANUBOT_USE_DOCKER}" != "true" ]; then 52 | echo >&2 "Exporting PDF manuscript using WeasyPrint" 53 | if [ -L images ]; then rm images; fi # if images is a symlink, remove it 54 | ln -s content/images 55 | pandoc \ 56 | --data-dir="$PANDOC_DATA_DIR" \ 57 | --defaults=common.yaml \ 58 | --defaults=html.yaml \ 59 | --defaults=pdf-weasyprint.yaml 60 | rm images 61 | fi 62 | 63 | # If Docker is available, use athenapdf to create PDF 64 | if [ "${BUILD_PDF}" != "false" ] && [ "${MANUBOT_USE_DOCKER}" == "true" ]; then 65 | echo >&2 "Exporting PDF manuscript using Docker + Athena" 66 | if [ "${CI}" = "true" ]; then 67 | # Incease --delay for CI builds to ensure the webpage fully renders, even when the CI server is under high load. 68 | # Local builds default to a shorter --delay to minimize runtime, assuming proper rendering is less crucial. 69 | MANUBOT_ATHENAPDF_DELAY="${MANUBOT_ATHENAPDF_DELAY:-5000}" 70 | echo >&2 "Continuous integration build detected. Setting athenapdf --delay=$MANUBOT_ATHENAPDF_DELAY" 71 | fi 72 | if [ -d output/images ]; then rm -rf output/images; fi # if images is a directory, remove it 73 | cp -R -L content/images output/ 74 | docker run \ 75 | --rm \ 76 | --shm-size=1g \ 77 | --volume="$(pwd)/output:/converted/" \ 78 | --security-opt=seccomp:unconfined \ 79 | arachnysdocker/athenapdf:2.16.0 \ 80 | athenapdf \ 81 | --delay=${MANUBOT_ATHENAPDF_DELAY:-1100} \ 82 | --pagesize=A4 \ 83 | manuscript.html manuscript.pdf 84 | rm -rf output/images 85 | fi 86 | 87 | # Create DOCX output (if BUILD_DOCX environment variable equals "true") 88 | if [ "${BUILD_DOCX}" = "true" ]; then 89 | echo >&2 "Exporting Word Docx manuscript" 90 | pandoc --verbose \ 91 | --data-dir="$PANDOC_DATA_DIR" \ 92 | --defaults=common.yaml \ 93 | --defaults=docx.yaml 94 | fi 95 | 96 | # Create LaTeX output (if BUILD_LATEX environment variable equals "true") 97 | if [ "${BUILD_LATEX}" = "true" ]; then 98 | echo >&2 "Exporting LaTeX manuscript" 99 | pandoc \ 100 | --data-dir="$PANDOC_DATA_DIR" \ 101 | --defaults=common.yaml \ 102 | --defaults=latex.yaml 103 | fi 104 | 105 | # Spellcheck 106 | if [ "${SPELLCHECK}" = "true" ]; then 107 | export ASPELL_CONF="add-extra-dicts $(pwd)/build/assets/custom-dictionary.txt; ignore-case true" 108 | 109 | # Identify and store spelling errors 110 | pandoc \ 111 | --data-dir="$PANDOC_DATA_DIR" \ 112 | --lua-filter spellcheck.lua \ 113 | output/manuscript.md \ 114 | | sort -fu > output/spelling-errors.txt 115 | echo >&2 "Potential spelling errors:" 116 | cat output/spelling-errors.txt 117 | 118 | # Add additional forms of punctuation that Pandoc converts so that the 119 | # locations can be detected 120 | # Create a new expanded spelling errors file so that the saved artifact 121 | # contains only the original misspelled words 122 | cp output/spelling-errors.txt output/expanded-spelling-errors.txt 123 | grep "’" output/spelling-errors.txt | sed "s/’/'/g" >> output/expanded-spelling-errors.txt || true 124 | 125 | # Find locations of spelling errors 126 | # Use "|| true" after grep because otherwise this step of the pipeline will 127 | # return exit code 1 if any of the markdown files do not contain a 128 | # misspelled word 129 | cat output/expanded-spelling-errors.txt | while read word; do grep -ion "\<$word\>" content/*.md; done | sort -h -t ":" -k 1b,1 -k2,2 > output/spelling-error-locations.txt || true 130 | echo >&2 "Filenames and line numbers with potential spelling errors:" 131 | cat output/spelling-error-locations.txt 132 | 133 | rm output/expanded-spelling-errors.txt 134 | fi 135 | 136 | echo >&2 "Build complete" 137 | -------------------------------------------------------------------------------- /build/environment.yml: -------------------------------------------------------------------------------- 1 | name: manubot 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - cairo=1.16.0 6 | - cairocffi=1.2.0 7 | - ghp-import=2.1.0 8 | - jinja2=3.1.2 9 | - jsonschema=4.17.0 10 | - librsvg=2.52.5 11 | - pandoc=2.19.2 12 | - pango=1.48.10 13 | - pip=22.3.1 14 | - python=3.11.0 15 | - requests-cache=0.9.6 16 | - requests=2.28.1 17 | - tomli=2.0.1 18 | - watchdog==2.1.9 19 | - weasyprint=53.4 20 | - yamllint=1.28.0 21 | - pip: 22 | - cffi==1.15.0 23 | - errorhandler==2.0.1 24 | - git+https://github.com/manubot/manubot@2914d720dfe02d2bda8781f8f784bc14d461e2e3 25 | - isbnlib==3.10.10 26 | - opentimestamps-client==0.7.1 27 | - opentimestamps==0.4.3 28 | - pandoc-eqnos==2.5.0 29 | - pandoc-fignos==2.4.0 30 | - pandoc-tablenos==2.3.0 31 | - pandoc-xnos==2.5.0 32 | - pandocfilters==1.5.0 33 | - panflute==2.2.3 34 | - psutil==5.9.4 35 | - pybase62==0.5.0 36 | - python-bitcoinlib==0.11.2 37 | - pyyaml==6.0 38 | -------------------------------------------------------------------------------- /build/pandoc/defaults/common.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults shared between Manubot output formats. 2 | from: markdown 3 | input-file: output/manuscript.md 4 | filters: 5 | - pandoc-fignos 6 | - pandoc-eqnos 7 | - pandoc-tablenos 8 | - pandoc-manubot-cite 9 | - citeproc 10 | wrap: preserve 11 | metadata: 12 | csl: build/assets/style.csl 13 | link-citations: true 14 | -------------------------------------------------------------------------------- /build/pandoc/defaults/docx.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for DOCX output. 2 | # Load on top of common defaults. 3 | to: docx 4 | output-file: output/manuscript.docx 5 | reference-doc: build/themes/default.docx 6 | resource-path: 7 | - '.' 8 | - content 9 | -------------------------------------------------------------------------------- /build/pandoc/defaults/html.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for HTML output. 2 | # Load on top of common defaults. 3 | to: html5 4 | output-file: output/manuscript.html 5 | # include-before-body: 6 | ### third-party plugins 7 | #- build/plugins/d3.html 8 | include-after-body: 9 | ### theme 10 | - build/themes/default.html 11 | ### first-party plugins 12 | - build/plugins/core.html # needed for all first-party plugins 13 | - build/plugins/accordion.html 14 | - build/plugins/anchors.html 15 | - build/plugins/attributes.html 16 | #- build/plugins/inline-svg.html 17 | - build/plugins/jump-to-first.html 18 | - build/plugins/lightbox.html 19 | - build/plugins/link-highlight.html 20 | - build/plugins/table-of-contents.html 21 | - build/plugins/tooltips.html 22 | ### third-party plugins 23 | - build/plugins/analytics.html 24 | - build/plugins/hypothesis.html 25 | - build/plugins/mathjax.html 26 | #- build/plugins/scite.html 27 | variables: 28 | document-css: false 29 | math: "" 30 | html-math-method: 31 | method: mathjax 32 | -------------------------------------------------------------------------------- /build/pandoc/defaults/latex.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for LaTeX output. 2 | # Load on top of common defaults. 3 | to: latex 4 | output-file: output/manuscript.tex 5 | -------------------------------------------------------------------------------- /build/pandoc/defaults/pdf-weasyprint.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for PDF output via weasyprint. 2 | # Load on top of HTML defaults. 3 | output-file: output/manuscript.pdf 4 | pdf-engine: weasyprint 5 | pdf-engine-opts: 6 | - '--presentational-hints' 7 | html-math-method: 8 | method: webtex 9 | url: 'https://latex.codecogs.com/svg.latex?' 10 | -------------------------------------------------------------------------------- /build/plugins/accordion.html: -------------------------------------------------------------------------------- 1 | 6 | 7 | 102 | 103 | 104 | 105 | 114 | 115 | 147 | -------------------------------------------------------------------------------- /build/plugins/analytics.html: -------------------------------------------------------------------------------- 1 | 6 | -------------------------------------------------------------------------------- /build/plugins/anchors.html: -------------------------------------------------------------------------------- 1 | 9 | 10 | 76 | 77 | 78 | 79 | 88 | 89 | 129 | -------------------------------------------------------------------------------- /build/plugins/attributes.html: -------------------------------------------------------------------------------- 1 | 8 | 9 | 86 | -------------------------------------------------------------------------------- /build/plugins/core.html: -------------------------------------------------------------------------------- 1 | 6 | 7 | 130 | -------------------------------------------------------------------------------- /build/plugins/d3.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 13 | -------------------------------------------------------------------------------- /build/plugins/hypothesis.html: -------------------------------------------------------------------------------- 1 | 6 | 7 | 87 | 88 | 89 | 90 | 100 | 101 | 167 | -------------------------------------------------------------------------------- /build/plugins/inline-svg.html: -------------------------------------------------------------------------------- 1 | 15 | 16 | 54 | -------------------------------------------------------------------------------- /build/plugins/jump-to-first.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 75 | 76 | 77 | 78 | 87 | 88 | 105 | -------------------------------------------------------------------------------- /build/plugins/lightbox.html: -------------------------------------------------------------------------------- 1 | 8 | 9 | 506 | 507 | 508 | 509 | 518 | 519 | 520 | 521 | 530 | 531 | 661 | -------------------------------------------------------------------------------- /build/plugins/link-highlight.html: -------------------------------------------------------------------------------- 1 | 9 | 10 | 126 | 127 | 158 | -------------------------------------------------------------------------------- /build/plugins/mathjax.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 17 | 18 | 23 | 24 | 54 | -------------------------------------------------------------------------------- /build/plugins/scite.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 13 | 14 | 50 | 51 | 63 | -------------------------------------------------------------------------------- /build/plugins/table-of-contents.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 237 | 238 | 239 | 240 | 250 | 251 | 405 | -------------------------------------------------------------------------------- /build/plugins/tooltips.html: -------------------------------------------------------------------------------- 1 | 8 | 9 | 417 | 418 | 419 | 420 | 429 | 430 | 431 | 432 | 441 | 442 | 508 | -------------------------------------------------------------------------------- /build/themes/default.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/manubot/rootstock/ca748bf4e80a830d7bee69a20b1fae18e028d9e6/build/themes/default.docx -------------------------------------------------------------------------------- /build/themes/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 667 | -------------------------------------------------------------------------------- /build/themes/nih-grant.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/manubot/rootstock/ca748bf4e80a830d7bee69a20b1fae18e028d9e6/build/themes/nih-grant.docx -------------------------------------------------------------------------------- /ci/.gitignore: -------------------------------------------------------------------------------- 1 | # SSH public and private keys 2 | deploy.key* 3 | -------------------------------------------------------------------------------- /ci/README.md: -------------------------------------------------------------------------------- 1 | # Continuous integration tools 2 | 3 | This directory contains tools and files for continuous integration (CI). 4 | Specifically, [`deploy.sh`](deploy.sh) runs on successful `main` branch builds that are not pull requests. 5 | The contents of `../webpage` are committed to the `gh-pages` branch. 6 | The contents of `../output` are committed to the `output` branch. 7 | 8 | For more information on the CI implementation, see the CI setup documentation in `SETUP.md`. 9 | -------------------------------------------------------------------------------- /ci/ai-revision-config.yaml: -------------------------------------------------------------------------------- 1 | files: 2 | ignore: 3 | - front\-matter 4 | - back\-matter 5 | matchings: 6 | - files: 7 | - .*\.md$ 8 | prompt: default 9 | -------------------------------------------------------------------------------- /ci/ai-revision-prompts.yaml: -------------------------------------------------------------------------------- 1 | prompts: 2 | abstract: | 3 | You are a scientist with copy-editing skills who will help in improving the text of a manuscript. Revise the following abstract of this manuscript so that it has a clear sentence structure and fits in a single paragraph. The revision should follow a context-content-conclusion (C-C-C) scheme, as follows: 1) The context portion communicates to the reader what gap the paper will fill. The first sentence orients the reader by introducing the broader field in which the manuscript's research is situated. Then, the context is narrowed until it lands on the open question that the research answers. A successful context section distinguishes the research's contributions from the current state-of-the-art, communicating what is missing in the current literature (i.e., the specific gap) and why that matters (i.e. the connection between the specific gap and the broader context). 2) The content portion (e.g. "here we") first describes the novel method or approach that was used to fill the gap, then presents an executive summary of results. 3) The conclusion portion interprets the results to answer the question that was posed at the end of the context portion. There may be a second part to the conclusion portion that highlights how this conclusion moves the broader field forward (e.g. "broader significance"). 4 | 5 | Input paragraph: {{ content }} 6 | 7 | Revised paragraph: 8 | 9 | introduction: | 10 | You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Introduction section to enhance clarity, reduce jargon, and maintain a scholarly tone. The revision should adhere to Markdown formatting and follow a Context-Content-Conclusion (C-C-C) structure. This structure begins by setting the stage with one or two sentences (Context), progresses through what is known from the literature (Content), and concludes by highlighting an aspect of the knowledge gap the manuscript addresses (Conclusion). Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]", and 4) the revised paragraph must encapsulate the entire revision, following the C-C-C structure, within a single, cohesive paragraph. 11 | 12 | Input paragraph: {{ content }} 13 | 14 | Revised paragraph: 15 | 16 | results: | 17 | You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Results section to enhance clarity, reduce jargon, maintain a scholarly tone, adhere to Markdown formatting and follow a Context-Content-Conclusion (C-C-C) structure. This structure begins with a sentence or two that set up the question that the paragraph answers (Context) (such as the following: "To verify that there are no artifacts...," "What is the test-retest reliability of our measure?," or "We next tested whether Ca2+ flux through L-type Ca2+ channels was involved"), the middle of the paragraph presents data and logic that pertain to the question (Content), and the paragraph ends with a sentence that answers the question (Conclusion). Your revision should: 1) ensure that the paragraph has the following structure: it starts with a sentence or two that set up the question that the paragraph answers (such as the following: "To verify that there are no artifacts...," "What is the test-retest reliability of our measure?," or "We next tested whether Ca2+ flux through L-type Ca2+ channels was involved."), the middle of the paragraph presents data and logic that pertain to the question, and the paragraph ends with a sentence that answers the question. Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]", and 4) the revised paragraph must encapsulate the entire revision, following the C-C-C structure, within a single, cohesive paragraph. 18 | 19 | Input paragraph: {{ content }} 20 | 21 | Revised paragraph: 22 | 23 | discussion: | 24 | You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Discussion section to enhance clarity, reduce jargon, maintain a scholarly tone, and adhere to Markdown formatting and follow a Context-Content-Conclusion (C-C-C) structure. This structure starts by describing an area of weakness or strength of the paper (Context), then evaluates the strength or weakness by linking it to the relevant literature (Content), and it often concludes by describing a clever, informal way of perceiving the contribution or by discussing future directions that can extend the contribution. Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]", and 4) the revised paragraph must encapsulate the entire revision, following the C-C-C structure, within a single, cohesive paragraph. 25 | 26 | Input paragraph: {{ content }} 27 | 28 | Revised paragraph: 29 | 30 | methods: | 31 | You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Methods section to enhance clarity, reduce jargon, maintain a scholarly tone, and adhere to Markdown formatting. Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) preserve technical details such as mathematical expressions, 3) ensure that equations (which could be numbered) are preserved and correctly defined, 4) preserve references to numbered equations, and 5) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]". 32 | 33 | Input paragraph: {{ content }} 34 | 35 | Revised paragraph: 36 | 37 | default: | 38 | Proofread the following paragraph that is part of a scientific manuscript. 39 | Keep all Markdown formatting, citations to other articles, mathematical 40 | expressions, and equations. 41 | 42 | Input paragraph: {{ content }} 43 | 44 | Proofread paragraph: 45 | -------------------------------------------------------------------------------- /ci/deploy.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## deploy.sh: run during a CI build to deploy manuscript outputs to the output and gh-pages branches on GitHub. 4 | 5 | # Set options for extra caution & debugging 6 | set -o errexit \ 7 | -o nounset \ 8 | -o pipefail 9 | 10 | # set environment variables for GitHub Actions 11 | REPO_SLUG=${GITHUB_REPOSITORY} 12 | COMMIT=${GITHUB_SHA} 13 | BRANCH=${DEFAULT_BRANCH:-main} 14 | 15 | # Add commit hash to the README 16 | OWNER_NAME="$(dirname "$REPO_SLUG")" 17 | REPO_NAME="$(basename "$REPO_SLUG")" 18 | export REPO_SLUG COMMIT OWNER_NAME REPO_NAME 19 | envsubst < webpage/README.md > webpage/README-complete.md 20 | mv webpage/README-complete.md webpage/README.md 21 | 22 | # Configure git 23 | git config --global push.default simple 24 | git config --global user.email "$(git log --max-count=1 --format='%ae')" 25 | git config --global user.name "$(git log --max-count=1 --format='%an')" 26 | git checkout "$BRANCH" 27 | 28 | # Configure deployment credentials 29 | MANUBOT_DEPLOY_VIA_SSH=true 30 | git remote set-url origin "git@github.com:$REPO_SLUG.git" 31 | if [ -v MANUBOT_SSH_PRIVATE_KEY ] && [ "$MANUBOT_SSH_PRIVATE_KEY" != "" ]; then 32 | echo >&2 "[INFO] Detected MANUBOT_SSH_PRIVATE_KEY. Will deploy via SSH." 33 | elif [ -v MANUBOT_ACCESS_TOKEN ] && [ "$MANUBOT_ACCESS_TOKEN" != "" ]; then 34 | echo >&2 "[INFO] Detected MANUBOT_ACCESS_TOKEN. Will deploy via HTTPS." 35 | MANUBOT_DEPLOY_VIA_SSH=false 36 | git remote set-url origin "https://$MANUBOT_ACCESS_TOKEN@github.com/$REPO_SLUG.git" 37 | else 38 | echo >&2 "[INFO] Missing MANUBOT_SSH_PRIVATE_KEY and MANUBOT_ACCESS_TOKEN. Will deploy via SSH." 39 | fi 40 | 41 | if [ $MANUBOT_DEPLOY_VIA_SSH = "true" ]; then 42 | # Decrypt and add SSH key 43 | eval "$(ssh-agent -s)" 44 | ( 45 | set +o xtrace # disable xtrace in subshell for private key operations 46 | if [ -v MANUBOT_SSH_PRIVATE_KEY ]; then 47 | base64 --decode <<< "$MANUBOT_SSH_PRIVATE_KEY" | ssh-add - 48 | else 49 | echo >&2 "Deployment will fail since neither of the following environment variables are set: MANUBOT_ACCESS_TOKEN or MANUBOT_SSH_PRIVATE_KEY." 50 | fi 51 | ) 52 | fi 53 | 54 | # Fetch and create gh-pages and output branches 55 | git remote set-branches --add origin gh-pages output 56 | git fetch origin gh-pages:gh-pages output:output || \ 57 | echo >&2 "[INFO] could not fetch gh-pages or output from origin." 58 | 59 | # Configure versioned webpage and timestamp 60 | manubot webpage \ 61 | --timestamp \ 62 | --no-ots-cache \ 63 | --checkout=gh-pages \ 64 | --version="$COMMIT" 65 | 66 | # Commit message 67 | MESSAGE="\ 68 | $(git log --max-count=1 --format='%s') 69 | [ci skip] 70 | 71 | This build is based on 72 | https://github.com/$REPO_SLUG/commit/$COMMIT. 73 | 74 | This commit was created by the following CI build and job: 75 | $CI_BUILD_WEB_URL 76 | $CI_JOB_WEB_URL 77 | " 78 | 79 | # Deploy the manubot outputs to output 80 | ghp-import \ 81 | --push \ 82 | --branch=output \ 83 | --message="$MESSAGE" \ 84 | output 85 | 86 | # Deploy the webpage directory to gh-pages 87 | ghp-import \ 88 | --no-jekyll \ 89 | --follow-links \ 90 | --push \ 91 | --branch=gh-pages \ 92 | --message="$MESSAGE" \ 93 | webpage 94 | 95 | if [ $MANUBOT_DEPLOY_VIA_SSH = "true" ]; then 96 | # Workaround https://github.com/travis-ci/travis-ci/issues/8082 97 | ssh-agent -k 98 | fi 99 | -------------------------------------------------------------------------------- /ci/install-spellcheck.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## install-spellcheck.sh: run during a CI build to install Pandoc spellcheck dependencies. 4 | 5 | # Set options for extra caution & debugging 6 | set -o errexit \ 7 | -o pipefail 8 | 9 | # --allow-releaseinfo-change for error on appveyor like "Repository ... changed its 'Label' value" 10 | sudo apt-get update --yes --allow-releaseinfo-change 11 | sudo apt-get install --yes aspell aspell-en 12 | wget --directory-prefix=build/pandoc/filters \ 13 | https://github.com/pandoc/lua-filters/raw/13c3fa7e97206413609a48a82575cb43137e037f/spellcheck/spellcheck.lua 14 | -------------------------------------------------------------------------------- /ci/install.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## install.sh: run during an AppVeyor build to install the conda environment 4 | ## and the optional Pandoc spellcheck dependencies. 5 | 6 | # Set options for extra caution & debugging 7 | set -o errexit \ 8 | -o pipefail 9 | 10 | wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh \ 11 | --output-document miniforge.sh 12 | bash miniforge.sh -b -p $HOME/miniconda 13 | source $HOME/miniconda/etc/profile.d/conda.sh 14 | hash -r 15 | conda config \ 16 | --set always_yes yes \ 17 | --set changeps1 no 18 | mamba env create --quiet --file build/environment.yml 19 | mamba list --name manubot 20 | conda activate manubot 21 | 22 | # Install Spellcheck filter for Pandoc 23 | if [ "${SPELLCHECK:-}" = "true" ]; then 24 | bash ci/install-spellcheck.sh 25 | fi 26 | -------------------------------------------------------------------------------- /content/00.front-matter.md: -------------------------------------------------------------------------------- 1 | {## 2 | This file contains a Jinja2 front-matter template that adds version and authorship information. 3 | Changing the Jinja2 templates in this file may cause incompatibility with Manubot updates. 4 | Pandoc automatically inserts title from metadata.yaml, so it is not included in this template. 5 | ##} 6 | 7 | {## Uncomment & edit the following line to reference to a preprinted or published version of the manuscript. 8 | _A DOI-citable version of this manuscript is available at _. 9 | ##} 10 | 11 | {## Template to insert build date and source ##} 12 | 13 | This manuscript 14 | {% if manubot.ci_source is defined and manubot.ci_source.provider == "appveyor" -%} 15 | ([permalink]({{manubot.ci_source.artifact_url}})) 16 | {% elif manubot.html_url_versioned is defined -%} 17 | ([permalink]({{manubot.html_url_versioned}})) 18 | {% endif -%} 19 | was automatically generated 20 | {% if manubot.ci_source is defined -%} 21 | from [{{manubot.ci_source.repo_slug}}@{{manubot.ci_source.commit | truncate(length=7, end='', leeway=0)}}](https://github.com/{{manubot.ci_source.repo_slug}}/tree/{{manubot.ci_source.commit}}) 22 | {% endif -%} 23 | on {{manubot.generated_date_long}}. 24 | 25 | 26 | {% if manubot.date_long != manubot.generated_date_long -%} 27 | Published: {{manubot.date_long}} 28 | {% endif %} 29 | 30 | ## Authors 31 | 32 | {## Template for listing authors ##} 33 | {% for author in manubot.authors %} 34 | + **{{author.name}}** 35 | {% if author.corresponding is defined and author.corresponding == true -%}^[✉](#correspondence)^{%- endif -%} 36 |
37 | {%- set has_ids = false %} 38 | {%- if author.orcid is defined and author.orcid is not none %} 39 | {%- set has_ids = true %} 40 | ![ORCID icon](images/orcid.svg){.inline_icon width=16 height=16} 41 | [{{author.orcid}}](https://orcid.org/{{author.orcid}}) 42 | {%- endif %} 43 | {%- if author.github is defined and author.github is not none %} 44 | {%- set has_ids = true %} 45 | · ![GitHub icon](images/github.svg){.inline_icon width=16 height=16} 46 | [{{author.github}}](https://github.com/{{author.github}}) 47 | {%- endif %} 48 | {%- if author.twitter is defined and author.twitter is not none %} 49 | {%- set has_ids = true %} 50 | · ![Twitter icon](images/twitter.svg){.inline_icon width=16 height=16} 51 | [{{author.twitter}}](https://twitter.com/{{author.twitter}}) 52 | {%- endif %} 53 | {%- if author.mastodon is defined and author.mastodon is not none and author["mastodon-server"] is defined and author["mastodon-server"] is not none %} 54 | {%- set has_ids = true %} 55 | · ![Mastodon icon](images/mastodon.svg){.inline_icon width=16 height=16} 56 | [\@{{author.mastodon}}@{{author["mastodon-server"]}}](https://{{author["mastodon-server"]}}/@{{author.mastodon}}) 57 | {%- endif %} 58 | {%- if has_ids %} 59 |
60 | {%- endif %} 61 | 62 | {%- if author.affiliations is defined and author.affiliations|length %} 63 | {{author.affiliations | join('; ')}} 64 | {%- endif %} 65 | {%- if author.funders is defined and author.funders|length %} 66 | · Funded by {{author.funders | join('; ')}} 67 | {%- endif %} 68 | 69 | {% endfor %} 70 | 71 | ::: {#correspondence} 72 | ✉ — Correspondence possible via {% if manubot.ci_source is defined -%}[GitHub Issues](https://github.com/{{manubot.ci_source.repo_slug}}/issues){% else %}GitHub Issues{% endif %} 73 | {% if manubot.authors|map(attribute='corresponding')|select|max -%} 74 | or email to 75 | {% for author in manubot.authors|selectattr("corresponding") -%} 76 | {{ author.name }} \<{{ author.email }}\>{{ ", " if not loop.last else "." }} 77 | {% endfor %} 78 | {% endif %} 79 | ::: 80 | -------------------------------------------------------------------------------- /content/01.abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract {.page_break_before} 2 | 3 | 4 | -------------------------------------------------------------------------------- /content/02.delete-me.md: -------------------------------------------------------------------------------- 1 | This manuscript is a template (aka "rootstock") for [Manubot](https://manubot.org/ "Manubot"), a tool for writing scholarly manuscripts. 2 | Use this template as a starting point for your manuscript. 3 | 4 | The rest of this document is a full list of formatting elements/features supported by Manubot. 5 | Compare the input (`.md` files in the `/content` directory) to the output you see below. 6 | 7 | ## Basic formatting 8 | 9 | **Bold** __text__ 10 | 11 | [Semi-bold text]{.semibold} 12 | 13 | [Centered text]{.center} 14 | 15 | [Right-aligned text]{.right} 16 | 17 | *Italic* _text_ 18 | 19 | Combined *italics and __bold__* 20 | 21 | ~~Strikethrough~~ 22 | 23 | 1. Ordered list item 24 | 2. Ordered list item 25 | a. Sub-item 26 | b. Sub-item 27 | i. Sub-sub-item 28 | 3. Ordered list item 29 | a. Sub-item 30 | 31 | - List item 32 | - List item 33 | - List item 34 | 35 | subscript: H~2~O is a liquid 36 | 37 | superscript: 2^10^ is 1024. 38 | 39 | [unicode superscripts](https://www.google.com/search?q=superscript+generator)⁰¹²³⁴⁵⁶⁷⁸⁹ 40 | 41 | [unicode subscripts](https://www.google.com/search?q=superscript+generator)₀₁₂₃₄₅₆₇₈₉ 42 | 43 | A long paragraph of text. 44 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 45 | Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 46 | Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. 47 | Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 48 | 49 | Putting each sentence on its own line has numerous benefits with regard to [editing](https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line) and [version control](https://rhodesmill.org/brandon/2012/one-sentence-per-line/). 50 | 51 | Line break without starting a new paragraph by putting 52 | two spaces at end of line. 53 | 54 | ## Document organization 55 | 56 | Document section headings: 57 | 58 | # Heading 1 59 | 60 | ## Heading 2 61 | 62 | ### Heading 3 63 | 64 | #### Heading 4 65 | 66 | ##### Heading 5 67 | 68 | ###### Heading 6 69 | 70 | ### A heading centered on its own printed page{.center .page_center} 71 | 72 | 73 | 74 | Horizontal rule: 75 | 76 | --- 77 | 78 | `Heading 1`'s are recommended to be reserved for the title of the manuscript. 79 | 80 | `Heading 2`'s are recommended for broad sections such as *Abstract*, *Methods*, *Conclusion*, etc. 81 | 82 | `Heading 3`'s and `Heading 4`'s are recommended for sub-sections. 83 | 84 | ## Links 85 | 86 | Bare URL link: 87 | 88 | [Long link with lots of words and stuff and junk and bleep and blah and stuff and other stuff and more stuff yeah](https://manubot.org) 89 | 90 | [Link with text](https://manubot.org) 91 | 92 | [Link with hover text](https://manubot.org "Manubot Homepage") 93 | 94 | [Link by reference][manubot homepage] 95 | 96 | [Manubot Homepage]: https://manubot.org 97 | 98 | ## Citations 99 | 100 | Citation by DOI [@doi:10.7554/eLife.32822]. 101 | 102 | Citation by PubMed Central ID [@pmc:PMC6103790]. 103 | 104 | Citation by PubMed ID [@pubmed:30718888]. 105 | 106 | Citation by Wikidata ID [@wikidata:Q56458321]. 107 | 108 | Citation by ISBN [@isbn:9780262517638]. 109 | 110 | Citation by URL [@{https://greenelab.github.io/meta-review/}]. 111 | 112 | Citation by alias [@deep-review]. 113 | 114 | Multiple citations can be put inside the same set of brackets [@doi:10.7554/eLife.32822; @deep-review; @isbn:9780262517638]. 115 | Manubot plugins provide easier, more convenient visualization of and navigation between citations [@doi:10.1371/journal.pcbi.1007128; @pubmed:30718888; @pmc:PMC6103790; @deep-review]. 116 | 117 | Citation tags (i.e. aliases) can be defined in their own paragraphs using Markdown's reference link syntax: 118 | 119 | [@deep-review]: doi:10.1098/rsif.2017.0387 120 | 121 | ## Referencing figures, tables, equations 122 | 123 | Figure @fig:square-image 124 | 125 | Figure @fig:wide-image 126 | 127 | Figure @fig:tall-image 128 | 129 | Figure @fig:vector-image 130 | 131 | Table @tbl:bowling-scores 132 | 133 | Equation @eq:regular-equation 134 | 135 | Equation @eq:long-equation 136 | 137 | ## Quotes and code 138 | 139 | > Quoted text 140 | 141 | > Quoted block of text 142 | > 143 | > Two roads diverged in a wood, and I— 144 | > I took the one less traveled by, 145 | > And that has made all the difference. 146 | 147 | Code `in the middle` of normal text, aka `inline code`. 148 | 149 | Code block with Python syntax highlighting: 150 | 151 | ```python 152 | from manubot.cite.doi import expand_short_doi 153 | 154 | def test_expand_short_doi(): 155 | doi = expand_short_doi("10/c3bp") 156 | # a string too long to fit within page: 157 | assert doi == "10.25313/2524-2695-2018-3-vliyanie-enhansera-copia-i-insulyatora-gypsy-na-sintez-ernk-modifikatsii-hromatina-i-svyazyvanie-insulyatornyh-belkov-vtransfetsirovannyh-geneticheskih-konstruktsiyah" 158 | ``` 159 | 160 | Code block with no syntax highlighting: 161 | 162 | ``` 163 | Exporting HTML manuscript 164 | Exporting DOCX manuscript 165 | Exporting PDF manuscript 166 | ``` 167 | 168 | ## Figures 169 | 170 | ![ 171 | **A square image at actual size and with a bottom caption.** 172 | Loaded from the latest version of image on GitHub. 173 | ](https://github.com/manubot/resources/raw/15493970f8882fce22bef829619d3fb37a613ba5/test/square.png "Square image"){#fig:square-image} 174 | 175 | ![ 176 | **An image too wide to fit within page at full size.** 177 | Loaded from a specific (hashed) version of the image on GitHub. 178 | ](https://github.com/manubot/resources/raw/15493970f8882fce22bef829619d3fb37a613ba5/test/wide.png "Wide image"){#fig:wide-image} 179 | 180 | ![ 181 | **A tall image with a specified height.** 182 | Loaded from a specific (hashed) version of the image on GitHub. 183 | ](https://github.com/manubot/resources/raw/15493970f8882fce22bef829619d3fb37a613ba5/test/tall.png "Tall image"){#fig:tall-image height=3in} 184 | 185 | ![ 186 | **A vector `.svg` image loaded from GitHub.** 187 | The parameter `sanitize=true` is necessary to properly load SVGs hosted via GitHub URLs. 188 | White background specified to serve as a backdrop for transparent sections of the image. 189 | Note that if you want to export to Word (`.docx`), you need to download the image and reference it locally (e.g. `content/images/vector.svg`) instead of using a URL. 190 | ](https://raw.githubusercontent.com/manubot/resources/main/test/vector.svg?sanitize=true "Vector image"){#fig:vector-image height=2.5in .white} 191 | 192 | ## Tables 193 | 194 | | *Bowling Scores* | Jane | John | Alice | Bob | 195 | |:-----------------|:-------------:|:-------------:|:-------------:|:-------------:| 196 | | Game 1 | 150 | 187 | 210 | 105 | 197 | | Game 2 | 98 | 202 | 197 | 102 | 198 | | Game 3 | 123 | 180 | 238 | 134 | 199 | 200 | Table: A table with a top caption and specified relative column widths. 201 | {#tbl:bowling-scores} 202 | 203 | | | Digits 1-33 | Digits 34-66 | Digits 67-99 | Ref. | 204 | |:--------|:-----------------------------------|:----------------------------------|:----------------------------------|:------------------------------------------------------------| 205 | | pi | 3.14159265358979323846264338327950 | 288419716939937510582097494459230 | 781640628620899862803482534211706 | [`piday.org`](https://www.piday.org/million/) | 206 | | e | 2.71828182845904523536028747135266 | 249775724709369995957496696762772 | 407663035354759457138217852516642 | [`nasa.gov`](https://apod.nasa.gov/htmltest/gifcity/e.2mil) | 207 | 208 | Table: A table too wide to fit within page. 209 | {#tbl:constant-digits} 210 | 211 | | | **Colors** | | 212 | |:--------:|:--------------------------------:|:--------------------:| 213 | | **Size** | **Text Color** | **Background Color** | 214 | | big | blue | orange | 215 | | small | black | white | 216 | 217 | Table: A table with merged cells using the `attributes` plugin. 218 | {#tbl: merged-cells} 219 | 220 | ## Equations 221 | 222 | A LaTeX equation: 223 | 224 | $$\int_0^\infty e^{-x^2} dx=\frac{\sqrt{\pi}}{2}$$ {#eq:regular-equation} 225 | 226 | An equation too long to fit within page: 227 | 228 | $$x = a + b + c + d + e + f + g + h + i + j + k + l + m + n + o + p + q + r + s + t + u + v + w + x + y + z + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9$$ {#eq:long-equation} 229 | 230 | ## Special 231 | 232 | [WARNING]{.semibold} _The following features are only supported and intended for `.html` and `.pdf` exports._ 233 | _Journals are not likely to support them, and they may not display correctly when converted to other formats such as `.docx`._ 234 | 235 | [Link styled as a button](https://manubot.org "Manubot Homepage"){.button} 236 | 237 | Adding arbitrary HTML attributes to an element using Pandoc's attribute syntax: 238 | 239 | ::: {#some_id_1 .some_class style="background: #ad1457; color: white; margin-left: 40px;" title="a paragraph of text" data-color="white" disabled="true"} 240 | Manubot Manubot Manubot Manubot Manubot. 241 | Manubot Manubot Manubot Manubot. 242 | Manubot Manubot Manubot. 243 | Manubot Manubot. 244 | Manubot. 245 | ::: 246 | 247 | Adding arbitrary HTML attributes to an element with the Manubot `attributes` plugin (more flexible than Pandoc's method in terms of which elements you can add attributes to): 248 | 249 | Manubot Manubot Manubot Manubot Manubot. 250 | Manubot Manubot Manubot Manubot. 251 | Manubot Manubot Manubot. 252 | Manubot Manubot. 253 | Manubot. 254 | 255 | 256 | Available background colors for text, images, code, banners, etc: 257 | 258 | `white`{.white} 259 | `lightgrey`{.lightgrey} 260 | `grey`{.grey} 261 | `darkgrey`{.darkgrey} 262 | `black`{.black} 263 | `lightred`{.lightred} 264 | `lightyellow`{.lightyellow} 265 | `lightgreen`{.lightgreen} 266 | `lightblue`{.lightblue} 267 | `lightpurple`{.lightpurple} 268 | `red`{.red} 269 | `orange`{.orange} 270 | `yellow`{.yellow} 271 | `green`{.green} 272 | `blue`{.blue} 273 | `purple`{.purple} 274 | 275 | Using the [Font Awesome](https://fontawesome.com/) icon set: 276 | 277 | 278 | 279 | 280 | 281 | 282 | [ 283 | **Light Grey Banner**
284 | useful for *general information* - [manubot.org](https://manubot.org/) 285 | ]{.banner .lightgrey} 286 | 287 | [ 288 | **Blue Banner**
289 | useful for *important information* - [manubot.org](https://manubot.org/) 290 | ]{.banner .lightblue} 291 | 292 | [ 293 | **Light Red Banner**
294 | useful for *warnings* - [manubot.org](https://manubot.org/) 295 | ]{.banner .lightred} 296 | -------------------------------------------------------------------------------- /content/90.back-matter.md: -------------------------------------------------------------------------------- 1 | ## References {.page_break_before} 2 | 3 | 4 |
5 | -------------------------------------------------------------------------------- /content/images/github.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/images/mastodon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/images/orcid.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/images/twitter.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/manual-references.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "id": "url:https://github.com/manubot/rootstock", 4 | "type": "webpage", 5 | "URL": "https://github.com/manubot/rootstock", 6 | "title": "manubot/rootstock GitHub repository", 7 | "container-title": "GitHub", 8 | "issued": { 9 | "date-parts": [ 10 | [ 11 | 2019 12 | ] 13 | ] 14 | }, 15 | "author": [ 16 | { 17 | "given": "Daniel", 18 | "family": "Himmelstein" 19 | } 20 | ] 21 | } 22 | ] 23 | -------------------------------------------------------------------------------- /content/metadata.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Manuscript Title" 3 | date: null # Defaults to date generated, but can specify like '2022-10-31'. 4 | keywords: 5 | - markdown 6 | - publishing 7 | - manubot 8 | lang: en-US 9 | authors: 10 | - github: johndoe 11 | name: John Doe 12 | initials: JD 13 | orcid: XXXX-XXXX-XXXX-XXXX 14 | twitter: johndoe 15 | mastodon: johndoe 16 | mastodon-server: mastodon.social 17 | email: john.doe@something.com 18 | affiliations: 19 | - Department of Something, University of Whatever 20 | funders: 21 | - Grant XXXXXXXX 22 | - github: janeroe 23 | name: Jane Roe 24 | initials: JR 25 | orcid: XXXX-XXXX-XXXX-XXXX 26 | email: jane.roe@whatever.edu 27 | affiliations: 28 | - Department of Something, University of Whatever 29 | - Department of Whatever, University of Something 30 | corresponding: true 31 | -------------------------------------------------------------------------------- /output/README.md: -------------------------------------------------------------------------------- 1 | # Generated citation / reference files 2 | 3 | The `output` branch contains files automatically generated by the manuscript build process. 4 | It consists of the contents of the `output` directory of the `main` branch. 5 | These files are not tracked in `main`, but instead written to the `output` branch by continuous integration builds. 6 | 7 | ## Files 8 | 9 | This directory contains the following files: 10 | 11 | + [`citations.tsv`](citations.tsv) is a table of citations extracted from the manuscript and the corresponding standard citations and citation IDs. 12 | + [`manuscript.md`](manuscript.md) is a markdown document of all manuscript sections, with citation strings replaced by citation IDs. 13 | + [`references.json`](references.json) is CSL-JSON file of bibliographic item metadata ([see specification](https://github.com/citation-style-language/schema/blob/master/csl-data.json)) for all references. 14 | + [`variables.json`](variables.json) contains variables that were passed to the jinja2 templater. These variables contain those automatically generated by the manubot as well as those provided by the user via the `--template-variables-path` option. 15 | 16 | Pandoc consumes `manuscript.md` and `references.json` to create the formatted manuscript, which is exported to `manuscript.html`, `manuscript.pdf`, and optionally `manuscript.docx`. 17 | -------------------------------------------------------------------------------- /setup.bash: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Setup Manubot 3 | # Based on https://github.com/manubot/rootstock/blob/main/SETUP.md 4 | # This is designed to be run from the bash terminal 5 | 6 | # Stop on first error. 7 | set -e 8 | 9 | usage() { 10 | echo "Usage: $0 [--owner text] [--repo text] [--yes]" 11 | echo "Guides the user through the creation of a new Manubot repository for their manuscript." 12 | echo 13 | echo "If no options are supplied a fully interactive process is used." 14 | echo "OWNER and REPO refer to the details of your manuscript repo location:" 15 | echo "i.e. https://github.com/OWNER/REPO." 16 | echo 17 | echo "Options:" 18 | echo " -o --owner GitHub user or organization name." 19 | echo " -r --repo Name of the repository for your new manuscript." 20 | echo " -y --yes Non-interactive mode. Continue script without asking for confirmation that the repo exists." 21 | echo " -s --ssh Use SSH to authenticate GitHub account. HTTPS is used by default." 22 | echo " Option only effective if --yes is also set, otherwise answer given in user interaction takes precedence." 23 | echo " -h --help Display usage information." 24 | 1>&2; exit 1; } 25 | 26 | # Check if to continue 27 | check(){ 28 | while true 29 | do 30 | echo "Once you have created your repo press enter to continue setup," 31 | read -r -p "or type exit to quit now: " input 32 | 33 | case $input in 34 | "") 35 | echo 36 | echo "Continuing Setup..." 37 | echo 38 | break 39 | ;; 40 | [eE][xX][iI][tT]) 41 | exit 1 42 | ;; 43 | *) 44 | echo 45 | echo "Invalid input, try again..." 46 | echo 47 | ;; 48 | esac 49 | done 50 | } 51 | 52 | # Option strings 53 | SHORT=o:r:hys 54 | LONG=owner:,repo:,help,yes,ssh 55 | 56 | YES=0 # continue when prompted 57 | AUTH=0 # used https or ssh auth 58 | 59 | # read the options 60 | OPTS=$(getopt --options $SHORT --long $LONG --name "$0" -- "$@") 61 | 62 | if [ $? != 0 ] ; then echo "Failed to parse options...exiting." >&2 ; exit 1 ; fi 63 | 64 | eval set -- "$OPTS" 65 | 66 | # extract options and their arguments into variables. 67 | while true ; do 68 | case "$1" in 69 | -o | --owner ) 70 | shift; 71 | OWNER=$1 72 | shift 73 | ;; 74 | -r | --repo ) 75 | REPO="$2" 76 | shift 2 77 | ;; 78 | -y | --yes ) 79 | YES=1 80 | shift 81 | ;; 82 | -s | --ssh ) 83 | AUTH=1; 84 | shift 85 | ;; 86 | -- ) 87 | shift 88 | break 89 | ;; 90 | -h | --help ) 91 | shift 92 | usage 93 | exit 1 94 | ;; 95 | *) 96 | echo "Internal error!" 97 | exit 1 98 | ;; 99 | esac 100 | done 101 | 102 | if [ -z "${OWNER}" ] || [ -z "${REPO}" ]; then 103 | echo "This script will take you through the setup process for Manubot." 104 | echo "First, we need to specify where to create the GitHub repo for your manuscript." 105 | echo 106 | echo "The URL will take this format: https://github.com/OWNER/REPO." 107 | echo "OWNER is your username or organization" 108 | echo "REPO is the name of your repository" 109 | echo 110 | read -r -p "Type in the OWNER now:" input 111 | OWNER=$input 112 | read -r -p "Type in the REPO now:" input 113 | REPO=$input 114 | fi 115 | 116 | # If using interactive mode, check remote repo exists. 117 | if [[ "$YES" == '0' ]]; then 118 | while true 119 | do 120 | echo 121 | read -r -p "Have you manually created https://github.com/${OWNER}/${REPO}? [y/n] " input 122 | 123 | case $input in 124 | [yY][eE][sS]|[yY]) 125 | 126 | echo 127 | echo "Continuing Setup..." 128 | echo 129 | break 130 | ;; 131 | [nN][oO]|[nN]) 132 | echo 133 | echo "Go to https://github.com/new and create https://github.com/${OWNER}/${REPO}" 134 | echo "Note: the new repo must be completely empty or the script will fail." 135 | echo 136 | check 137 | break 138 | ;; 139 | *) 140 | echo 141 | echo "Invalid input, try again..." 142 | echo 143 | ;; 144 | esac 145 | done 146 | else 147 | echo "Setting up https://github.com/${OWNER}/${REPO}" 148 | fi 149 | 150 | # Clone manubot/rootstock 151 | echo 152 | echo "Cloning Rootstock..." 153 | echo 154 | git clone --single-branch https://github.com/manubot/rootstock.git ${REPO} 155 | cd ${REPO} 156 | 157 | echo 158 | echo "Setup tracking of remote..." 159 | 160 | # Configure remotes 161 | git remote add rootstock https://github.com/manubot/rootstock.git 162 | 163 | # Check auth method 164 | if [[ "$YES" == '0' ]]; then 165 | while true 166 | do 167 | echo 168 | read -r -p "Would you like to use SSH to authenticate your GitHub account? [y/n] " input 169 | 170 | case $input in 171 | [yY][eE][sS]|[yY]) 172 | AUTH=1 173 | break 174 | ;; 175 | [nN][oO]|[nN]) 176 | AUTH=0 177 | break 178 | ;; 179 | *) 180 | echo 181 | echo "Invalid input, try again..." 182 | echo 183 | ;; 184 | esac 185 | done 186 | fi 187 | 188 | case $AUTH in 189 | 0) 190 | echo 191 | echo "Setting origin URL using its https web address" 192 | echo 193 | git remote set-url origin https://github.com/${OWNER}/${REPO}.git 194 | ;; 195 | 1) 196 | echo 197 | echo "Setting origin URL using SSH" 198 | echo 199 | git remote set-url origin git@github.com:$OWNER/$REPO.git 200 | ;; 201 | esac 202 | 203 | git push --set-upstream origin main 204 | 205 | # To use GitHub Actions only: 206 | echo "Setup for GitHub Actions ONLY..." 207 | # remove AppVeyor config 208 | git rm .appveyor.yml 209 | # remove ci/install.sh (only used by AppVeyor) 210 | git rm ci/install.sh 211 | 212 | # Update README 213 | echo "Updating README..." 214 | # Perform substitutions 215 | sed "s/manubot\/rootstock/${OWNER}\/${REPO}/g" README.md > tmp && mv -f tmp README.md 216 | sed "s/manubot\.github\.io\/rootstock/${OWNER}\.github\.io\/${REPO}/g" README.md > tmp && mv -f tmp README.md 217 | 218 | echo "Committing rebrand..." 219 | git add --update 220 | git commit --message "Brand repo to $OWNER/$REPO" 221 | git push origin main 222 | echo 223 | echo "Setup complete" 224 | echo 225 | echo "The new repo has been created at $(pwd)" 226 | echo 227 | echo "A good first step is to modify content/metadata.yaml with the relevant information for your manuscript." 228 | echo 229 | -------------------------------------------------------------------------------- /webpage/README.md: -------------------------------------------------------------------------------- 1 | # Output directory containing the formatted manuscript 2 | 3 | The [`gh-pages`](https://github.com/$REPO_SLUG/tree/gh-pages) branch hosts the contents of this directory at . 4 | The permalink for this webpage version is . 5 | To redirect to the permalink for the latest manuscript version at anytime, use the link . 6 | 7 | ## Files 8 | 9 | This directory contains the following files, which are mostly ignored on the `main` branch: 10 | 11 | + [`index.html`](index.html) is an HTML manuscript. 12 | + [`manuscript.pdf`](manuscript.pdf) is a PDF manuscript. 13 | 14 | The `v` directory contains directories for each manuscript version. 15 | In general, a version is identified by the commit hash of the source content that created it. 16 | 17 | ### Timestamps 18 | 19 | The `*.ots` files in version directories are OpenTimestamps which can be used to verify manuscript existence at or before a given time. 20 | [OpenTimestamps](https://opentimestamps.org/) uses the Bitcoin blockchain to attest to file hash existence. 21 | The `deploy.sh` script run during continuous deployment creates the `.ots` files through its `manubot webpage` call. 22 | There is a delay before timestamps get confirmed by a Bitcoin block. 23 | Therefore, `.ots` files are initially incomplete and should be upgraded at a later time, so that they no longer rely on the availability of a calendar server to verify. 24 | The `manubot webpage` call during continuous deployment identifies files matched by `webpage/v/**/*.ots` and attempts to upgrade them. 25 | You can also manually upgrade timestamps, by running the following in the `gh-pages` branch: 26 | 27 | ```shell 28 | ots upgrade v/*/*.ots 29 | rm v/*/*.ots.bak 30 | git add v/*/*.ots 31 | ``` 32 | 33 | Verifying timestamps with the `ots verify` command requires running a local bitcoin node with JSON-RPC configured, at this time. 34 | 35 | ## Source 36 | 37 | The manuscripts in this directory were built from 38 | [`$COMMIT`](https://github.com/$REPO_SLUG/commit/$COMMIT). 39 | -------------------------------------------------------------------------------- /webpage/images: -------------------------------------------------------------------------------- 1 | v/latest/images -------------------------------------------------------------------------------- /webpage/index.html: -------------------------------------------------------------------------------- 1 | v/latest/index.html -------------------------------------------------------------------------------- /webpage/manuscript.pdf: -------------------------------------------------------------------------------- 1 | v/latest/manuscript.pdf --------------------------------------------------------------------------------