couscousphp / couscous

Couscous is good.

layout
home

Couscous generates a GitHub pages website from your markdown documentation.

Everything is documented on couscous.io.

What follows is the documentation for contributors.

How Couscous works?

Couscous was designed to be as simple as possible. By embracing simplicity, it becomes extremely simple to extend.

Website generation

The website generation is composed of a list of steps to process the Project model object:

interface Step
{
    /**
     * Process the given project.
     *
     * @param Project $project
     */
    public function __invoke(Project $project);
}

Steps are very granular, thus extremely easy to write and test. For example:

• LoadConfig: load the couscous.yml config file
• InstallDependencies: install the dependencies (using yarn, npm or bower)
• LoadMarkdownFiles: load the content of all the *.md files in memory
• RenderMarkdown: render the markdown content
• WriteFiles: write the in-memory processed files to the target directory
• …

For example, here is a step that would preprocess Markdown files to put the word "Couscous" in bold:

class PutCouscousInBold implements \Couscous\Step
{
    public function __invoke(Project $project)
    {
        /** @var MarkdownFile[] $markdownFiles */
        $markdownFiles = $project->findFilesByType('Couscous\Model\MarkdownFile');

        foreach ($markdownFiles as $file) {
            $file->content = str_replace('Couscous', '**Couscous**', $file->content);
        }
    }
}

Couscous uses PHP-DI for wiring everything together with dependency injection.

The full list of steps is configured in src/Application/config.php.

Website deployment

Couscous deploys by cloning (in a temp directory) the current repository, checking out the gh-pages branch, generating the website inside it, committing and pushing.

In the future, Couscous will support several deployment strategies.

Contributing

See the CONTRIBUTING file.

License

Couscous is released under the MIT License.

couscous's Issues

Relative url not targeting a markdown file

Hi,

I just noticed a small issue with Couscous. When a link target a relative path (not a markdown file), I think the link should point to the github repo instead of keeping a relative url.

For example, in this page of the Redaktilo website (/cc @gnugat), there is a link targeting a test case (../tests/example/BundleRegistrationTest.php). Of course when clicking this link, you get a 404.

Anyway, this tools is awesome! :)

Support for .ico files as assets

It seems .ico files are not copied by Couscous like the other assets.

Ship with a beautiful default template

Updating template is not reflected in preview

Thanks for sharing Cousous!

When updating template files changes do not seem to be automatically reflected in the running preview server automatically. After restarting the server the updates are reflected as expected.

In both situations the preview server writes the following to the console:

File changes detected, regenerating
Generating [repo path] to [repo path]/.couscous/generated
Copying template files
Processing README.md

I am using PHP 5.5.17 and Couscous dev-master.

Support Markdown Extra

I don't think we support Markdown Extra right now, because we are using mnapoli/FrontYaml which uses Parsedown by default.

We should have it use ParsedownExtra.

We would also probably need tests to ensure we support Markdown Extra.

There should be no required file to run Couscous

Today Couscous requires a couscous.yml and a template directory. It should work without them using default configs end templates.

Replace default template?

We now have 3 templates:

• "Default"

  

• Light

  

• Basic

  

My suggestion is to rename "Default" into "Dark", that way we have "Light" and "Dark" themes. And then we switch the theme by default to use the "Light" one, because I think it's more standard and universal…

What do you think?

Add a `preview` variable in layouts to know when working in "preview"

Give information about requirements

We should write something somewhere about requirements as I just found that lessc is needed to allow Couscous to work correctly

Problems requiring Couscous with Composer

Couscous requires a non-stable version of BowerPHP (because no stable version exist, see Bee-Lab/bowerphp#93).

composer require couscous/couscous then throws an error that no stable version of BowerPHP can be found… (unless end users explicitly allow non-stable versions).

In composer.json we tried requiring 0.2.*@alpha, 0.2.2-alpha or 1.0.x-dev of BowerPHP but with the same results…

A solution (a bit extreme) would be to fork BowerPHP and tag a release. We would have to maintain that fork up to date until BowerPHP reaches a stable version… That's a bit of work, I'd like to avoid that if there's an alternative.

Which tool to format PR content?

Hello there,

Should we use something like https://github.com/gushphp/gush to format PR always the same way?

Maybe another tool...

Simplify templates

Instead of having:

website/
    default.twig
    other.twig
    public/
        css/
        js/

We could simply have:

website/
    default.twig
    other.twig
    css/
    js/

RestructuredText support

Any chance to get restructuredText support ?

Improve documentation

The documentation needs to be updated for 1.0.

Also on the website it would be good to add a sidebar containing links to all the documentation articles. (like in https://github.com/CouscousPHP/Template-Default)

www.couscous.io leads to domain parked page

www.couscous.io leads to a page, which says the domain is parked. Non www domain works well.

Domain name: couscous.io?

Choose and setup a domain.

couscous.io?

Remote templates: ignore some files

Remote templates can contain files, like https://github.com/CouscousPHP/Template-Default

• README.md
• screenshot.png

We don't want those files when the template is used.

Get the page list in a Twig variable

In order to build menus and lists (e.g. in blogs) more easily, it would be good to have the file list and file tree in Twig.

Example:

All pages:
    {% for page in pageList %}
        {{ page }}
    {% endfor %}

Would render:

All pages:
    index.html
    docs/some-documentation.html

Similarly, we would need to have the list also available as a tree, but be able to get the files of a specific directory:

Documentation articles:
    {% for page in pageTree['docs'] %}
        {% if page is not iterable %}
            {{ page }}
        {% endif %}
    {% endfor %}

Documentation articles:
    some-documentation.html

Rename the Composer package

From mnapoli/couscous to couscous/couscous.

Symlink the public directory instead of copying for preview

This will improve the dev process, no need to relaunch the server to regenerate the website.

Auto-link to GitHub issue in Markdown

GitHub will automatically create a link to an issue in Markdown with text like this:

Implemented in #123.

Couscous could support the same behavior and turn #123 into [#123](https://github.com/CouscousPHP/Couscous/issues/123).

It would only work if the GitHub project is configured in couscous.yml, e.g.:

github:
    user: symfony
    repo: console

(same options that what's used in the default template)

Twig compilation prevent to reload templates

When templates are modified, Twig will not reload them.

The reason for this is that Twig compiles file templates into PHP code, using a class name that contains the file name. Given the file name has not changed (only the content), the generated PHP class already exists and Twig skips re-creating it.

See twigphp/Twig#914

Add Couscous to "Awesome PHP"

Add Couscous here: https://github.com/ziadoz/awesome-php#static-site-generators

couscous preview not working

I do get the following error message on couscous preview:

Copying template files
Processing README.md
PHP Warning: date(): It is not safe to rely on the system's timezone settings. You are required to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. in phar:///home/triplem/couscous/src/CLI/PreviewCommand.php on line 72

Drop support for PHP 5.3?

Should we support PHP 5.3? Without PHP 5.4 the built-in webserver doesn't work, so that defeats the purpose of couscous preview…

I'm afraid people having PHP 5.3 would never even use it because of that, so I guess it's pointless to keep support for it. And since Couscous will only be run on development machines, having a recent PHP version is usually not a problem (compared to upgrading in production).

Auto-generate HTML IDs for headers

It's pretty useful to be able to link to a sub-section of a page. To do this, we need to have HTML IDs on headers, like this:

<h2 id="introduction">Introduction</h2>

This is possible with Markdown Extra (supported by Couscous by default):

## Introduction {#introduction}

But that requires to use that notation everywhere. What would be good is to automatically add the IDs for headers.

For example: https://github.com/piwik/developer-documentation/blob/63348af258b258de5dd66d3978f5726d5717380c/app/helpers/Markdown/TitleIdPreprocessor.php

Note: I believe we can't copy-paste that code directly since its license is GPLv3 and Couscous is MIT (are they compatible?). We probably need to rewrite it.

We could probably implement that as a Step that is executed before Markdown is parsed.

This feature is super-useful to be able to specific sections in menus, or also to share the URL of a specific section of the documentation.

Replace calls to `exec()` with a PHP class

We have this pattern a lot:

$command = "git clone $gitUrl $directory 2>&1";
exec($command, $gitOutput, $returnValue);
if ($returnValue !== 0) {
    throw new \RuntimeException(implode(PHP_EOL, $gitOutput));
}

Problems:

• exec() makes the code impossible to unit test
• code duplication

Solution:

Add a utility class with a run($command) method that runs CLI commands. It would automatically throw the exception and do the stderr redirect (2>&1).

That would allow us to mock that class in unit tests, just like we can mock the filesystem thanks to Symfony's Filesystem class.

Search feature

Hi,
I will better if there is a search area in the documentation.

Possible solution :

• a simple google/bing/whatever search box area
• using https://github.com/olivernn/lunr.js be we need in this case an indexer
• there is also externals crawler (that cost some money) that generate index or index + search
• you can be inspire by this kjekyll plugins : https://github.com/slashdotdash/jekyll-lunr-js-search
• there is also this : http://tapirgo.com/

There is probably more, the result I get up, is just by searching a couple of minute on google.

Error using couscous on Symfony 2 project

Using the latest version of couscous on a Symfony 2 project I get this error:

PHP Warning: require_once(/home/maxime/workspace/Claroline/../../../autoload.php): failed to open stream: No such file or directory in /home/maxime/workspace/Claroline/couscous.phar on line 24
PHP Fatal error: require_once(): Failed opening required '/home/maxime/workspace/Claroline/../../../autoload.php' (include_path='.:/usr/share/php:/usr/share/pear') in /home/maxime/workspace/Claroline/couscous.phar on line 24

To get that I just executed the following commands, as on the couscous website:

• curl -OS http://couscousphp.github.io/Couscous/couscous.phar
• php couscous.phar preview .

Couscous is looking for an autoload.php file three level up from the folder project, so in /home, instead in the vendor folder.

Failure if no website/public directory

[UnexpectedValueException]
  RecursiveDirectoryIterator::__construct(.../website/public):
  failed to open dir: No such file or directory

Couscous should handle the case where no website/public directory exists.

Automatically add the "website" directory to the ignore list

The website/ directory must be ignored (like vendor/) by default.

Automatically create the gh-pages branch if it doesn't exist

Couscous should work out of the box.

Rename cousous.yml to .couscous.yml?

Awesome project!

What do you think about renaming couscous.yml to .couscous.yml for consistency with Git, Travis, Scrutinizr, PHP CS Fixer... and to avoid visually polluting the main repository with on Unix?

Run tests against lowest Composer dependencies

http://mnapoli.fr/test-lowest-dependencies/

We should do it as well to ensure Couscous will work in all setups

No address for server when previewing

Preview features seems to be broken.

I launched it as said on the website:

php couscous.phar preview .

Here is what I get:

Generating /home/maxime/workspace/Claroline to /home/maxime/workspace/Claroline/.couscous/generated
Fetching template from https://github.com/CouscousPHP/Template-Default.git
Server running on .

I don't have any address to look at, and http://localhost:8000/ is not accessible either.

Errors while running Couscous on some distros

A friend of mine gave it a spin on CentOS (PHP 5.5):

Generating /etc/yum.repos.d to /etc/yum.repos.d/.couscous/generated
No couscous.yml configuration file found, using default config
Fetching template from https://github.com/CouscousPHP/Template-Light.git
PHP Warning:  date(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. in phar:///usr/local/bin/couscous/src/Model/WatchList/FinderWatch.php on line 21
PHP Warning:  date(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. in phar:///usr/local/bin/couscous/src/Model/WatchList/FinderWatch.php on line 21
Server running on 127.0.0.1:8000
PHP Warning:  array_map(): An error occurred while invoking the map callback in phar:///usr/local/bin/couscous/src/Model/WatchList/WatchList.php on line 39

  [InvalidArgumentException]                  
  "2014-12-01 18:41:08" is not a valid date.  

preview [--target="..."] [address] [source]

Then tried OpenSuse, PHP 5.6.3:

PHP Fatal error:  Uncaught exception 'Exception' with message 'The "phar" extension is required to run this archive.' in /root/docker-flatip/couscous.phar:8
Stack trace:
#0 {main}
  thrown in /root/docker-flatip/couscous.phar on line 8

With OpenSuse, PHP 5.4.34 is the same as CentOS.

Couscous "init:template" command

That would be cool to have a command to initialize a template:

$ couscous init:template

That would create the directory and maybe put a very very simple Twig template in there, just to get started.

There is currently the InitCommand (couscous init) but it's not up to date so I have disabled it for now. It can be used as a basis for that.

Things to rename

There are some things that don't have a very good name, here are renames to do:

• template should be layout in markdown files (the template is the whole theme with CSS & all, the layout is the specific twig file)
• default layout page.twig should be default.twig

More tests & improve code coverage

Currently the code coverage is very low: (16% at the time of writing)

Tests are mainly functional tests. It would be good to write unit tests.

If anybody wants to write unit tests, you need to be aware that PHPUnit is set up so that you need to use @covers to have code coverage. Here is an example:

/**
 * @covers Couscous\Model\Metadata
 */
class MetadataTest extends \PHPUnit_Framework_TestCase
{

Without @covers, no coverage data is taken into account for this test class.

This is to ensure that the code coverage data is taken into account only the tested class, and not for other classes (i.e. it avoids "accidental" code coverage).

Speed up external templates

If using a template from a git url the template appears to be cloned each time the site is generarted. That makes the preview process slower.

It would be nice if we could keep using the the checkout if the url does not change. To ensure we use the latest version we could pull.

Auto-generate HTML ids for headers

It's pretty useful to be able to link to a sub-section of a page. To do this, we need to have HTML IDs on headers, like this:

<h2 id="introduction">Introduction</h2>

This is possible with Markdown Extra (supported by Couscous by default):

## Introduction {#introduction}

But that requires to use that notation everywhere.

What would be good is to automatically add the IDs for headers. To do this, we can probably reuse what I wrote here in Piwik's documentation: TitleIdPreprocessor. We could implement that as a new step in Couscous.

Scrutinizer

• add the project on Scrutinizer (https://scrutinizer-ci.com/g/CouscousPHP/Couscous/)
• add the badge to the README

Website: optimize the background image

The background image is 1.3 Mb right now, which is way too much. It needs to be optimized, but still display correctly on a large display.

If anybody who knows how to do this correctly wants to give it a shot, I'm all hears. I don't have good photo editor software (e.g. photoshop).

Warn the user that we require PHP 5.4

In the case that a user runs the Phar with PHP 5.3, we should probably die with an explicit message instead of waiting for an error to happen.

I think a simple if () in bin/couscous would be enough…

Convert Markdown files and links to lower-case

On Couscous and other projects there is a CHANGELOG.md or CONTRIBUTING.md. When we want to link to it in the website, it gives this ugly URL: http://php-di.org/CONTRIBUTING.html

it would be nice to turn those links and HTML files in lower case.

use latest parsedown

Tables are not rendered correctly, while the latest parsedown does this. could be that it is a version issue?

Try the following:

Name	Contribution
Dumm1	Provided the longest Source Code
Dumm2	Service Scripts
MyName	Several Plugin

http://parsedown.org/demo

Logo + favicon

We need a logo and favicon for the website and the GitHub organization.

Composer require Couscous ver 1.0 fail

When I config my composer.json get couscous version 1.0 like that

{
    "require": {
        "couscous/couscous": "~1.0"
    }
}

And, after that, run composer install, raise error

Problem 1
    - Installation request for couscous/couscous ~1.0 -> satisfiable by couscous/couscous[1.0.0].
    - couscous/couscous 1.0.0 requires beelab/bowerphp 0.1.*@alpha -> no matching package found.

But, if I config with @stable, composer get and install Couscous ver 0.3.3

Reduce the size of the phar

A friend reported to me that the Phar was around 6 Mo, which is a bit much. On top of that, he experienced slow downloads from the website (GitHub hosting). I'm sure we can reduce it by removing useless extra files (tests? website?) from the generated phar.

Add documentation for running Couscous in Travis?

Today to generate and deploy Couscous, users have:

• to install Couscous locally
• to run couscous deploy

An alternative would be to run Couscous in Travis so that it's redeployed everytime anybody pushes. I'm guessing that can be practical for some projects (no need to have a maintainer that rebuilds the website everytime). Of course we would still keep all the documentation about running Couscous locally.

It could be good to try to set that up for this repository itself, and then add it to the documentation.