Code Monkey home page Code Monkey logo

ibis's Introduction

Ibis logo

Artwork by Eric L. Barnes and Caneco from Laravel News โค๏ธ.


This PHP tool helps you write eBooks in markdown. Run ibis build and an eBook will be generated with:

  1. A cover photo.
  2. Clickable auto-generated table of contents.
  3. Code syntax highlighting.
  4. Available in 2 themes. Light and dark.

Ibis was used to create Laravel Queues in Action, an eBook I published in August 2020. Click here for the sample.

Installation

Make sure you have PHP7.3 or above installed on your system and that your gd extension is enabled in your php.ini file.

First, install the composer package globally:

composer global require themsaid/ibis

Then, run this command inside an empty directory:

ibis init

This will create the following files and directories:

  • /assets
  • /assets/fonts
  • /assets/cover.jpg
  • /assets/theme-light.html
  • /assets/theme-dark.html
  • /content
  • /ibis.php

You may configure your book by editing the /ibis.php configuration file.

Writing Your eBook

The init command will create sample .md files inside the content folder. You can explore those files to see how you can write your book. This sample content is taken from Laravel Queues in Action.

Inside the content directory, you can write multiple .md files. Ibis uses the headings to divide the book into parts and chapters:

# Part 1

<h1> tags define the start of a part. A separate PDF page will be generated to print the part title and any content below.

## Chapter 1

<h2> tags define the start of a chapter. A chapter starts on a new page always.

### Starting with Ibis

<h3> tags define different titles inside a chapter.

Adding different quotes

Three different types of quotes can be added: quote, warning, and notice.

>{quote} This is a quote.

>{warning} This is a warning.

>{notice} This is a notice.

Using images

Images can be stored in the content folder and then brought in like this:

![Screenshot 1](content/screenshot-1.png)

Adding a cover image

To use a cover image, add a cover.jpg in the assets/ directory (or a cover.html file if you'd prefer a HTML-based cover page). If you don't want a cover image, delete these files.

Using Fonts

Edit your /ibis.php configuration files to define the font files to be loaded from the /assets/fonts directory. After that you may use the defined fonts in your themes (/assets/theme-light.html & /assets/theme-dark.html).

Generating PDF eBook

ibis build

Ibis will parse the files in alphabetical order and store the PDF file in /export.

The default is to generate the PDF using the light theme, to generate a PDF using the dark theme:

ibis build dark

Generating A Sample

ibis sample

ibis sample dark

This command will use the generated files from the ibis build command to generate samples from your PDF eBook. You can configure which pages to include in the sample by updating the /ibis.php file.

Development

This project uses PHP CS Fixer with a code standard defined in .php_cs.

To review code out of style, you can run the fix command as a dry run. Run the composer script like this:

composer run csfix-review

To fix the source code, run the following composer script:

composer run csfix

Credits

License

The MIT License (MIT). Please see License File for more information.

ibis's People

Contributors

aarondfrancis avatar aaronsaray avatar alexellis avatar amitmerchant1990 avatar dcblogdev avatar eberkund avatar elminson avatar jer3m01 avatar liorchamla avatar owenvoke avatar phikhi avatar s-moon avatar shalvah avatar tarekdj avatar themsaid avatar thinkverse avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

ibis's Issues

[Feature Request]: post cover

Now, there are:

  • cover (if exists) (image or html)
  • TOC
  • content (pages from markdown)

I would like to suggest having an optional "post cover" after the cover and TOC. This may be useful for having the typical page with inscription "thanks to..." or some quotes.

My proposal is:

  • if exists a /assets/post-cover.html file (with some content, like cover.html) (so not mandatory), append the post-cover.html file after the cover in buildPdf() function.

If you want, I can open a PR for this.

[Feature Request]: define file name for cover

In order to load jpg file and png file as cover, make asset/cover.jpg configurable.

My proposal is to add image in config['cover']['image']

    /**
     * Cover photo position and dimensions
     */
    'cover' => [
        'position' => 'position: absolute; left:0; right: 0; top: -.2; bottom: 0;',
        'dimensions' => 'width: 210mm; height: 297mm; margin: 0;',
        'image' => 'cover.png',
    ],

Then, replace cover.jpg with the content of ['cover']['image'].
Remember to Update the stub/ibis.php file

I'm going to create a PR

Sample files

Is there any chance of including the input files in the example zip file, as well as the output files? Or perhaps a separate simple example of some of the features used?

Conflicts with Laravel Valet

Trying to run the global installer composer global require themsaid/ibis I'm getting a conflict with the current Laravel Valet:

Changed current directory to /Users/ericlbarnes/.composer
Using version ^0.1.1 for themsaid/ibis
./composer.json has been updated
Running composer update themsaid/ibis --with-all-dependencies
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - illuminate/container v8.13.0 requires illuminate/contracts ^8.0 -> found illuminate/contracts[v8.0.0, ..., v8.13.0] but it conflicts with another require.
    - laravel/valet v2.12.0 requires illuminate/container ~5.1|^6.0|^7.0|^8.0 -> satisfiable by illuminate/container[v8.13.0].
    - laravel/valet is locked to version v2.12.0 and an update of this package was not requested.

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

[Feature Request]: Allow user to specify the markdown directory

Now the markdown files are loaded from : $currentPath.'/content'
Where $currentPath is retrieved from getcwd().

My proposal is to allow the user to define the directory (absolute or relative) where to load markdown files.
The input argument could be --markdowndir=

If you want i could open a PR.

More colored containers

I use ibis for two PDFs I write and I like to use the notice and warning containers. However, I would like to propose that ibis introduces two more. tip and danger. The inspiration comes from VuePress.

I think the following containers could be benefitial:

  • notice: blue
  • tip: green
  • warning: yellow
  • danger: red

Arabic letters

Hi, Mohamed Said,

This is the first run through to keep in touch with you.

I attempted to utilize Arabic letters in your task ibis, it is brilliant.

In any case, is there any approach to set the direction from left to right when utilizing Arabic letters.

Respects,

Mostafa Gaber

Error: command `ibis` not found

Operating System: Linux Ubuntu 20.04

I ran the command composer global require themsaid/ibis and completed the installation successfully. Upon running ibis init, I get an error.

Question: Custom Theming

Great package @themsaid . Thank you!

I have a question: Does Ibis currently support custom theming? If not, is there plan for it in the future/Will you be open to such PR?

Can't install on PHP 7.4.4

Hello

I wanted to take a look at your tool but I couldn't install it even though I have PHP 7.4 and I have activated the GD extension in my php.ini.

Can you confirm that ibis can be installed with 7.4.4?

Thanks

C:\temp\book>composer global require themsaid/ibis
Changed current directory to C:/Users/Christophe/AppData/Roaming/Composer
Using version ^0.1.3 for themsaid/ibis
./composer.json has been updated
Running composer update themsaid/ibis
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - mpdf/mpdf[v8.0.0, ..., v8.0.3] require php ^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0 || ~7.3.0 -> your php version (7.4.4) does not satisfy that requirement.
    - mpdf/mpdf[v8.0.4, ..., v8.0.7] require paragonie/random_compat ^1.4|^2.0|9.99.99 -> found paragonie/random_compat[v1.4.0, v1.4.1, v1.4.2, v1.4.3, v2.0.0, ..., v2.0.19, v9.99.99] but the package is fixed to v9.99.100 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
    - themsaid/ibis v0.1.3 requires mpdf/mpdf ^8.0 -> satisfiable by mpdf/mpdf[v8.0.0, ..., v8.0.7].
    - Root composer.json requires themsaid/ibis ^0.1.3 -> satisfiable by themsaid/ibis[v0.1.3].

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.

HTML required as an output for technical books

Hi, the HTML is required for working through technical labs where you need to copy and paste code samples, my eBook has a lot of samples and unfortunately they are broken up over multiple pages which makes working through the content difficult.

Given that this seems to create HTML then print that to PDF, it should be possible. Can you consider just outputting HTML by default along with the main PDF?

It would be a great addition.

I also would prefer to give a PNG (high-res) than JPEG for the cover image, but had to fork IBIS to achieve that. Can you make it look for either - or move to PNG by default (lossless)?

Alex

arabic language supported

when i write my md`s in arabic language, and build my book, after open the book i see just squares

use variable ?

I everyone i have question there is possibility to pass php variable into md file ? thanks

Code Standard Enforcement

Hello - and thanks for creating this awesome project. :)

I noticed your .php_cs configuration file and the composer command. However, I noticed some code could be out of standard. In addition, since everyone uses different code standard tools, they might not have php-cs-fixer installed globally. That being said, I'd like to propose the following:

  • Ensure all files are code standard compliant
  • Add php-cs-fixer as a local project install as a composer dev dependency
  • Add a script to composer to do a dry-run for people who'd like to review their code standard changes - and to be ran as part of CI
  • Add a github action to run the code standard on pushes and pull requests

I'll submit a pull request with these suggested updates for your review.

cant install on php8

i guess this is a very common issue now, so when trying to install ibis on php8 the result is the following:

`Your requirements could not be resolved to an installable set of packages.

Problem 1
- mpdf/mpdf[v8.0.0, ..., v8.0.3] require php ^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0 || ~7.3.0 -> your php version (8.0.0) does not satisfy that requirement.
- mpdf/mpdf[v8.0.4, ..., v8.0.7] require php ^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0 || ~7.3.0 || ~7.4.0 -> your php version (8.0.0) does not satisfy that requirement.
- themsaid/ibis v0.1.3 requires mpdf/mpdf ^8.0 -> satisfiable by mpdf/mpdf[v8.0.0, ..., v8.0.7].
- Root composer.json requires themsaid/ibis ^0.1.3 -> satisfiable by themsaid/ibis[v0.1.3].`

Support for equations?

Are you considering the idea of adding support for Latex formulas? For example

$\int_0^2 x^2dx$

Where do I put images?

The images I've added come out looking like this..

noimg

Where and how would you suggest I add them?

Support for alternate markdown table notation

Following this issue thread #27 it appears that the following type of markdown tables are supported:

Command Description
Test Test

i.e. raw format:

| Command | Description |
|---------|-------------|
| Test    | Test        |

However, the following format is not supported:

Short Flag Long Flag Description
-l - Show Results in long format

i.e. in raw code format:

|**Short Flag**   |**Long Flag**   |**Description**   |
|:---|:---|:---|
|`-l`|<center>-</center>|Show Results in long format|

This format is valid markdown that works here on Github, but when rendered in the PDF, it comes out as a literal string:

Screen Shot 2021-10-09 at 11 38 07

I could potentially do a PR to add this new type of parser, but would need some guidance on where to start.

Valet requirement

Perfect project for me because I write everything in Markdown. However I just got finished updating everything Composer needed in order to finally install it and after ibis init I got the error: Valet only supports the Mac operating system. I'm trying to run this in WSL 2 on Windows 10. I checked the composer.json in the Ibis repo and don't see Laravel or Valet as a dependency, so I'm wondering if this is a side effect of my setup or a dependency of a dependency.

Any way to get this running on Windows or Linux?

Enforce required PHP version and Add Security Advisories

In its current construction, this app supports php 7.3 and above I believe. Looking at the open tickets and testing, it doesn't look like it supports PHP 8 yet.

Additionally, the roave/security-advisories composer dependency provides other limitations in the form of conflicts to stop insecure library additions.

I suggest:

  • add php 7.3+ to the composer php requirements
  • add the roave security advisories branch

How to include images

Thanks your this package, I've been eagerly waiting for it!

I'm wondering, how do I include images in my pages? Right now I'm trying:

![Image title](images/filename.jpg)

Where I created a folder called "images" inside the "assets" folder. However, this image appears as broken in the PDF.

Thanks for your time!

HTML based cover

Hi, this tool is really simple to use compared to some other solutions I have tried so kudos on that ๐Ÿ‘

It would be great if it could support HTML based covers rather than just a JPG. I am hoping I will be able to use this tool for creating reports and the cover I had in mind was more textual with a different layout. Are you open to supporting this use case? I imagine as this project grows, some more configuration options in ibis.php would allow it to support many different document use cases in addition to ebooks.

Feature: build life cycle callbacks (prehtml, prepdf, etc)

I tend to use C style inline comments (// comment here) in my markdown files because:

  • my editor theme grays out <!-- html --> comments making them hard to read/see
  • I like being able to use // TODO: ... and // NOTE: ... as specific notes to myself for future review

It would be helpful if I could register a standard event hook callback in my ibis.php that BuildCommand.php issues before converting a file to HTML from markdown.

I have a working proof of concept in my own fork of the repo that introduces a prehtml() global function that one can optionally provide in their ibis.php if they want to preprocess their markdown content for whatever reason.

Docker Image?

Is it possible to have an official 'ibis docker image'?

Installation

First, Thanks for releasing this great tool!

I've installed globally using

composer global require themsaid/ibis

Then went into an empty directory and ran:

ibis init

I then get:

PHP Warning:  require(/Users/dave/.composer/vendor/themsaid/ibis/vendor/autoload.php): failed to open stream: No such file or directory in /Users/dave/.composer/vendor/themsaid/ibis/ibis on line 10

Warning: require(/Users/dave/.composer/vendor/themsaid/ibis/vendor/autoload.php): failed to open stream: No such file or directory in /Users/dave/.composer/vendor/themsaid/ibis/ibis on line 10
PHP Fatal error:  require(): Failed opening required '/Users/dave/.composer/vendor/themsaid/ibis/vendor/autoload.php' (include_path='.:/usr/local/Cellar/php/7.4.11/share/php/pear') in /Users/dave/.composer/vendor/themsaid/ibis/ibis on line 10

Fatal error: require(): Failed opening required '/Users/dave/.composer/vendor/themsaid/ibis/vendor/autoload.php' (include_path='.:/usr/local/Cellar/php/7.4.11/share/php/pear') in /Users/dave/.composer/vendor/themsaid/ibis/ibis on line 10

Have I missed a step?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.