Editing files
You can edit CyberRiskOp files directly on GitHub without having a local copy. Before beginning, contributors will need to create a free GitHub account. Click here for more information on GitHub accounts.
Important Links
Editing files in the CyberRiskOp
1. Navigate to one of the CyberRiskOp repositories and locate the file you want to edit.
2. Click on the 🖊️ icon in the upper right corner to open the file editor.
3. In the Edit file tab, you can now make any changes that you want to add to the file.
4. To preview your changes, click on the Preview tab to the right.
5. You can add a commit message to the file below. This is a short message that describes the change made to the file. More than one author can be included in the commit message. Click Here to learn how.
6. Once everything is done, click Propose changes.
7. Enter in a title and description for your pull request.
8. Finally, click on Create pull request.
jekyll-book-framework
Table of Contents
- Introduction
- Features
- Usage
- Deployment
- Documentation
- Contributing
- Release History
- Authors and acknowledgment
Introduction
This tool is inspired by Antoine Fauchié's excellent thesis (Vers un système modulaire de publication : éditer avec le numérique). The project on which his thesis was based served as the basis for the development of jekyll-book-framework
.
To get an idea, you can see the demo of this project.
Features
- Markdown writing format
- PDF auto generation with paged.js
- Static site generator with Jekyll
- Clean interface
Usage
Clone the project using git:
git clone https://github.com/michaelravedoni/jekyll-book-framework.git
cd jekyll-book-framework
Or, download manually : Download the project and unzip it. Once done:
- Rename the directory with the name you want. For example:
my-book
(JEKYLL-BOOK-NAME
in the following steps). - Edit the configuration file (
_data/meta.yml
) as needed. - Edit the stylesheet variables located in
book/styles
. - Edit the book/work content files located in
book/text
. - Install the dependencies, start and deploy the project (see below).
Install
To run the project, you have to install Jekyll (and therefore Ruby). Also install npm if you want to easily deploy the FTP life application (see deploy) or to easily run the project.
After you install Ruby, install the Jekyll CLI:
$ gem install jekyll bundler
Enter in your project's folder:
cd JEKYLL-BOOK-NAME
Install all Ruby and npm dependencies, such as Jekyll and plugins:
bundle install
npm run install
Start
To start and serve the project for development, run:
npm run dev
Preview your local book in your web browser at http://localhost:4000
.
To build the component for production, run:
npm run build
Deployment
At some point you will probably want to publish what you have built so that it can be shared with the wider world. The projects currently supports three methods of deployment: Netlify, Github Pages and Rsync.
Netlify
Assuming you have created a repository for this project on GitHub, sign up or log in to Netlify using your GitHub account.
- Click the big button labeled new site from Git
- Select your repository
- Configure the basic build settings: choose appropriate branch (
master
by default) - You can set the default build command to
jekyll
and the publish directory to_site/
, but this is not necessare since thenetlify.toml
file has all the information pre-configured. - Netlify will auto-generate a site URL for you, or you can set it yourself. The default example uses
http://JEKYLL-BOOK-NAME.netlify.com
. Set this as yourbaseurl
in_config.yml
. - Now, every time you push up a commit to
master
on GitHub, Netlify will automatically rebuild your site using the settings innetlify.toml
. Pretty cool!
GitHub Pages
Unlike Netlify, GitHub Pages does not support continuous deployment. This means you will need to manually deploy the site by running a script provided in bin/github-deploy.sh
in the project folder.
- In
_config-github.yml
, set thebaseurl
in the format that GitHub Pages expects (https://yourusername.github.io/JEKYLL-BOOK-NAME for most sites). - At this point you can run
bin/github-deploy.sh
and everything will be pushed up to GitHub on thegh-pages
branch:
npm run deploy-github
It may take a few moments for everything to become visible online. If you get git errors when deploying because of upstream changes, you can always delete the gh-pages
branch on GitHub and re-run the deploy script.
If you want, you can remove the _site
directory from your .gitignore
file so that you can check built files into version control.
Via FTP (RSync)
Any web server capable of hosting static files will work (S3, FTP server, etc.). For deploying the site via FTP (RSync), follow this instructions. In the main project folder /
, run (if not already done) :
npm install
Rename the env-model.json
file in env.json
and open-it. Then fill the <user>
, <host>
and <path/>
with your FTP remote server informations. For example:
username_example@example.ftp.com:web/JEKYLL-BOOK-NAME/
Then, to deploy the app, run :
npm run stage #For testing on your test server
npm run stage-dry #If you want to run a dry test
npm run deploy-rsync #For the production server
npm run deploy-rsync-dry #If you want to run a dry test
Documentation
Architecture
-
data/meta.yml
: Contains all the metadata of the project and the book. Change the variables on your needs. -
book
: Contains all the contents of the book.book/text
contains all the markdown files. If you have a translation,book/fr
contains the translated book. -
index.md
: Home page of the book (editable) -
_bibliography
: Contains the bibliographys in BibTex format (.bib file) necessary for the jekyll-scholar plugin -
materials
: Directory containing all the files (image, text, media) and drafts of the book for discussion -
images
: Directory containing the files and images necessary for the book -
output
: Directory containing the output formats of the book -
_includes
,_layouts
,_sass
,_plugins
and others: Files necessary for the working of Jekyll
All the files and directories can be modified for customization and your own needs.
Branches
For each development or writing idea, we recommend creating a specific branch in your project. This will facilitate project discussions and monitoring.
Commits format
To make the use of Git more understandable, here is a list of conventions for writing commits:
admin
: technical management of the repository or sitestyle
: stylesedit
: content editionfix
: correction, modification following a remarkorg
: organization of files, repository, sitegen
: automation for the generation of the different files and formatstest
: test (but normally reported in a specific branch)
Contributing
We’re really happy to accept contributions from the community, that’s the main reason why we open-sourced it! There are many ways to contribute, even if you’re not a technical person.
- Fork this project
- Create your feature branch (
git checkout -b feature/fooBar
) - Commit your changes (
git commit -am 'Add some fooBar'
) - Push to the branch (
git push origin feature/fooBar
) - Create a new Pull Request
Release History
You will find the releases history in the release section. For more detail, you can check the changelog.md file.
Roadmap
- Styles and css restructuration
- i18n
- auto pdf genarator
- epub, mobi and markdown export
- create different work layouts
- define a workflow (version, edition, translation)
- create template for git issues (Github and GitLab)
- create deploy command for GitLab
Authors and acknowledgment
- Michael Ravedoni - Initial work - michaelravedoni
- Antoine Fauchié - Inspirated work and project - antoinentl
See also the list of contributors who participated in this project.
- electric-book - Inspiration - Electric Book Works
- Quire - Inspiration - Getty Publications