couscousphp / template-readthedocs Goto Github PK

This project forked from readthedocs/sphinx_rtd_theme

Couscous template based on readthedocs.org Sphinx theme

License: Other

CSS 7.28% JavaScript 5.12% Twig 14.07% Sass 73.52%

template-readthedocs's Introduction

currentMenu	currentSubMenu
home	configuration

Read The Docs template for Couscous

Read The Docs builds websites using a Sphinx theme. That theme is open source and released under the MIT license.

This project is a port of the Sphinx theme to Couscous.

Usage

To use the template, set it up in your couscous.yml configuration file:

template:
    url: https://github.com/CouscousPHP/Template-ReadTheDocs

Configuration

Here are all the variables you can set in your couscous.yml:

# Base URL of the published website
baseUrl: http://username.github.io/project

# Used to link to the GitHub project
github:
    user: myself
    repo: my-project

title: My project
subTitle: This is a great project.

# The left menu bar
menu:
    items:
        home:
            text: FAQ
            # You can use relative urls
            relativeUrl: doc/faq.html
        foo:
            text: Another link
            # Or absolute urls
            absoluteUrl: https://example.com
        group:
            text: Link with a sub menu
            relativeUrl: group.html
            items:
                anchor:
                    text: Some anchor
                    relativeUrl: group.html#some-anchor
                link:
                    text: Some link
                    absoluteUrl: https://example.com

Note that the menu items can also contain HTML:

home:
    text: "<i class=\"fa fa-github\"></i> FAQ"
    relativeUrl: doc/faq.html

TODO

Want to help?

The original template came with a lot of SASS files and features. Some features are not ported to this Couscous template (e.g. the search).

What would be good to do:

find a way to cleanly handle the SASS files and the theme.css (which contains the generated/minified CSS) which right now are duplicates. Relying on SASS wouldn't be a good idea though since it would be end-users have to install SASS.
clean up unused CSS and SASS style (e.g. search bar, …)

In the meantime, the original minified theme.css is used and it works just great.

template-readthedocs's People

Contributors

Stargazers

Watchers

template-readthedocs's Issues

Lists do not format

Lists do not format correctly with this theme AFAICT.

This is the source md:

* list item 1
* list item 2

This is the output:

list item 1
list item 2

Expecting:

list item 1
list item 2

System Details:

PHP 7.0.22-0ubuntu0.17.04.1 (cli) (built: Aug  8 2017 22:03:30) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2017 Zend Technologies
    with Zend OPcache v7.0.22-0ubuntu0.17.04.1, Copyright (c) 1999-2017, by Zend Technologies

Composer version 1.2.2 2016-11-03 17:43:15

container-interop/container-interop 1.2.0   Promoting the interoperability of container objects (DIC, SL, etc.)
couscous/couscous                   1.6.1
erusev/parsedown                    1.6.3   Parser for Markdown.
erusev/parsedown-extra              0.7.1   An extension of Parsedown that adds support for Markdown Extra.
mnapoli/front-yaml                  1.5.2
padraic/humbug_get_contents         1.0.4   Secure wrapper for accessing HTTPS resources with file_get_contents for PHP 5.3+
padraic/phar-updater                1.0.4   A thing to make PHAR self-updating easy and secure.
phine/exception                     1.0.0   A PHP library for improving the use of exceptions.
phine/observer                      2.0.1   A PHP library that implements the observer pattern.
phine/path                          1.1.0   A PHP library for improving the use of file system paths.
phine/phar                          1.0.2   A PHP library for creating and reading (without the phar extension) PHP archives.
php-di/invoker                      1.3.3   Generic and extensible callable invoker
php-di/php-di                       5.4.3   The dependency injection container for humans
php-di/phpdoc-reader                2.0.1   PhpDocReader parses @var and @param values in PHP docblocks (supports namespaced class names with t...
psr/container                       1.0.0   Common Container Interface (PHP FIG PSR-11)
psr/log                             1.0.2   Common interface for logging libraries
symfony/console                     v3.3.6  Symfony Console Component
symfony/debug                       v3.3.6  Symfony Debug Component
symfony/filesystem                  v3.3.6  Symfony Filesystem Component
symfony/finder                      v3.3.6  Symfony Finder Component
symfony/polyfill-mbstring           v1.5.0  Symfony polyfill for the Mbstring extension
symfony/process                     v3.3.6  Symfony Process Component
symfony/yaml                        v3.3.6  Symfony Yaml Component
twig/twig                           v1.34.4 Twig, the flexible, fast, and secure template language for PHP

Feature request for adding dividers or other html elements

Hi, I just wrote this bit of code. item.type can be all html elements that can be child of li element like span or a...

It can be used to make dividers for exemple

<{{ item.type is defined ? item.type : 'a' }} class="reference internal {{ itemId == currentMenu ? 'current' }}" href="{{ item.absoluteUrl|default(baseUrl ~ '/' ~ item.relativeUrl) }}"> {{ item.text|raw }} </{{ item.type is defined ? item.type : 'a' }}>

Also, are there a native way to do a submenu ? Should I implement one ?

(@mnapoli sorry for issue on light-theme, just a mistake cause I was on the wrong page :) )

Floating Menu?

Are there any options for floating the menu so that it's viewable on long pages?

Thanks

currentMenu not working

I have added the markdown in my configuration,md file as follows

currentMenu : configuration

and in in my couscous.yml file menus are like as follows

menu:
    items:
        getting-started:
            text: Get started
            relativeUrl: deployment-guide.html
        documentation:
            text: Installation Guide
            relativeUrl: deployment-guide.html
        configuration:
            text: Configuration Guide
            relativeUrl: configuration.html
        troubleshooting:
            text: Troubleshooting
            relativeUrl: troubleshooting.html
        templates:
            text: Release Summary
            relativeUrl: release-summary.html
        faqs:
            text: FAQs
            relativeUrl: faqs.html

Still i cant set the active menu as i am not getting current_menu in default.twig.
Anyone have solutions or found same issue

need menu sections

Only one level menu can not satisfy me

Thanks ~