<commit_before>---
title: Project structure 
layout: manpage 
author: <NAME>
---

The project directory
=====================

A typical Urubu project directory looks as follows:

```
Makefile
_site.yml
_layouts/_base.html
         page.html
         ...
_python/__init__.py
        validators.py
        filters.py
css/...
js/...
index.md
folder1/index.md
        file1.md
        pic1.png
        ...
folder2/index.md
        file2.md
        file3.md
        ...
```

Files and directories with pathnames starting with an underscore `_` are
special. They are used during processing, but excluded from the built website.
Their function will be discussed below.  

The `css` and `js` directories are just an example of how CSS style sheets and
javascript files could be organized. You can use any organization that you
prefer.

Content files are in Markdown format and should have the `.md` extension. You
have complete freedom in organizing them in directories. However, every
directory should have an `index.md` file, including the top-level directory.

Processing rules
================

Urubu generates a website by processing the files and directory in the project
directory, and putting the result in a `_build` subdirectory. The processing
depends on the pathname as follows:

* a `Makefile` is not copied to the build. 
* files and directories starting with a
dot `.` or underscore `_` are not copied to the build.
* Markdown files with extension `.md` are converted to a
html file that is put into the build in the same relative location.
* all other files and directories are copied unmodified to the build in the
same relative location.

As a result of the project organization and the build process, the
structure of the build matches the structure of the project directory.
The relative location of all files is thus preserved.

Special files
=============

`_site.yml`
-----------

This file contains site configuration info in YAML format.
Currently, a single attribute is predefined: 

Attribute      | Description
---------------|-------------
`reflinks`     | Holds a mapping from reference ids to link objects.

Link objects are a mapping with an `url` key that maps to the link url and
a `title` key that maps to the link title. 

You can define additional attributes that will be made available as
site variables to the template engine. The following is an example of a
`_site.yml` file:

```
brand: Urubu 

reflinks:
    content_license:
        url: http://creativecommons.org/licenses/by-sa/3.0/
        title: CC-BY-SA License
    software_license:
        url: http://www.gnu.org/licenses/agpl-3.0.txt
        title: GNU Affero General Public License
    markdown:
        url: http://daringfireball.net/projects/markdown/  
        title: Markdown
```

`_layouts`
----------

This directory contains the templates that define the available layouts.
They are used by the Jinja2 template engine to render html pages.
The templates files should have the `.html` extension.

`_python`
---------<commit_msg>Doc. for commit 'Allow file/link extensions different than .html'<commit_after>---
title: Project structure 
layout: manpage 
author: <NAME>
---

The project directory
=====================

A typical Urubu project directory looks as follows:

```
Makefile
_site.yml
_layouts/_base.html
         page.html
         ...
_python/__init__.py
        validators.py
        filters.py
css/...
js/...
index.md
folder1/index.md
        file1.md
        pic1.png
        ...
folder2/index.md
        file2.md
        file3.md
        ...
```

Files and directories with pathnames starting with an underscore `_` are
special. They are used during processing, but excluded from the built website.
Their function will be discussed below.  

The `css` and `js` directories are just an example of how CSS style sheets and
javascript files could be organized. You can use any organization that you
prefer.

Content files are in Markdown format and should have the `.md` extension. You
have complete freedom in organizing them in directories. However, every
directory should have an `index.md` file, including the top-level directory.

Processing rules
================

Urubu generates a website by processing the files and directory in the project
directory, and putting the result in a `_build` subdirectory. The processing
depends on the pathname as follows:

* a `Makefile` is not copied to the build. 
* files and directories starting with a
dot `.` or underscore `_` are not copied to the build.
* Markdown files with extension `.md` are converted to a
html file that is put into the build in the same relative location.
* all other files and directories are copied unmodified to the build in the
same relative location.

As a result of the project organization and the build process, the
structure of the build matches the structure of the project directory.
The relative location of all files is thus preserved.

Special files
=============

`_site.yml`
-----------

This file contains site configuration info in YAML format.
Currently, a single attribute is predefined: 

Attribute      | Description
---------------|-------------
`reflinks`     | Holds a mapping from reference ids to link objects.
`file_ext`     | Change default file extension (`'.html'`) for processed `.md` files
`link_ext`     | Change default file extension (`'.html'`) for links to site's pages

Link objects, for the `reflinks` attribute, are a mapping with an `url` key that maps
to the link url and a `title` key that maps to the link title. 

The file extension attributes , `file_ext` and `link_ext`, are both usually set to the
same value (i.e. `'.php'`), unless the target site has .htaccess rewrite rules that
affect the file extensions.

Examples of this are sites that internally redirect pages like `www.test.com/account`
to `www.test.com/account.htm`. For this case, one would need to set `file_ext` to
`'.htm'`, so Urubu generated files have the `.htm` extension, whereas `link_ext` would
be set to `''`, so that the `a href` links are directed to the files without extension.

Otherwise, `file_ext` and `link_ext` should be set to the same extension, specially
during testing, so that the simple web server invoked by `urubu serve` works fine,
as well as any web server that does not rewrite the file extensions of the requests. 

You can define additional attributes that will be made available as
site variables to the template engine. The following is an example of a
`_site.yml` file:

```
brand: Urubu 

reflinks:
    content_license:
        url: http://creativecommons.org/licenses/by-sa/3.0/
        title: CC-BY-SA License
    software_license:
        url: http://www.gnu.org/licenses/agpl-3.0.txt
        title: GNU Affero General Public License
    markdown:
        url: http://daringfireball.net/projects/markdown/  
        title: Markdown
        
file_ext: '.htm'  # Change default file extension ('.html')
link_ext: '.htm'  # Change default link extension ('.html')
```

`_layouts`
----------

This directory contains the templates that define the available layouts.
They are used by the Jinja2 template engine to render html pages.
The templates files should have the `.html` extension.

`_python`
---------
{'fraction_non_alphanumeric': 0.09654696132596685, 'fraction_numerical': 0.0030386740331491712, 'mean_word_length': 3.2221574344023325, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7184885', 'n_tokens_mistral': 1963, 'n_tokens_neox': 1892, 'n_words': 940}