Skip to content

Latest commit

 

History

History
62 lines (49 loc) · 3.28 KB

CONTRIBUTING.md

File metadata and controls

62 lines (49 loc) · 3.28 KB

How it works?

BoP uses markdown templates in _sources for each site published at https://bookofproofs.github.io/. The templates work similarly to JeKyll (if you are already familiar with it).

However, we compile the markdown files into html using PYTHON scripts in the _compile folder. The reason why we do not use JeKyll and 're-invent' the wheel is more flexibility. We incorporate some features improving user experience, e.g.:

Getting started

To contribute to the site, follow these generic steps:

  1. Clone the repository.
    1. Optional: Change the constant in the script _compile/BopCompiler.py to True: 
      class BopCompiler:
    local = False
      Note: this is only necessary if you want to test hyperlinks locally.
  2. Add new or amend existing markdown files.
  3. Run _compile/main.py. Before this step, you might be required to install some missing python packages using pip.
  4. Control the locally generated files in your browser. The root file is docs/index.html.
    1. If something is still not the way you want it, repeat steps 2 to 4.

Once you are ready with your editions:

  1. Optional (If you changed the constant in 1.i):
    1. Change the script _compile/BopCompiler.py back to False.
    2. Recompile (like in step 3) to correct local hyperlinks to remote ones again.
  2. Add to git any new files you added in the folder _sources/ or its subfolders and(!) any new files that were auto-generated in docs/.
  3. Commit and push to a new branch and make a change request.

Further Help

Please check out our cheat sheets

  1. cheat_sheet_source_files.md
  2. cheat_sheet_attributing
  3. cheat_sheet_layouts
  4. cheat_sheet_naming_identifying_ordering
  5. cheat_sheet_categories
  6. cheat_sheet_layout_epoch
  7. cheat_sheet_layout_topic
  8. cheat_sheet_bibliography
  9. cheat_sheet_layout_person
  10. (more cheat sheets to come)