Well, if you're reading this, you probably just started a new Veritable project. Congrats! Now, what do you do from here?. Don't worry, we've got your back.
An image of a cute doggo.
This README was generated upon running the
$ veritable init [project name]command.
In your project directory, you'll see a few Veritable specific files and folders:
- The
.veritablefolder - The
srcfolder - The
.veritableignorefile - This
README.mdfile
The .veritable folder is a hidden folder containing some of your project specific configuration files.
(You shouldn't have to edit any of these files directly - they can be edited through the $ veritable configure FILE command.
There is a list of a the commands and the arguments they take later on.)
The src folder contains all files (such as an image, etc.) you want to embed in a page.
The .veritableingore file is a .gitignore-style file that can be used to hide specific files and folders from the showing up on your project website.
By default, it's set to ignore the src folder and all hidden folders/files.
This README.md file is what you're reading right now.
It's intended to be used as a getting started guide and reference, so you can delete it after you're done reading it.
Let's talk about how Veritable turns your folders and files into a website.
When you initiate a folder, a .veritable folder is added to the project's base directory.
This is how the The Veritable Project source code tells whether or not the folder it's in a a Veritable project, so it's important to keep this folder around.
Let's see what the file structure of a finished Veritable project might look like:
+ Project Name
|-+ .veritable
| |-- [configuration files]
|
|-+ src
| |-- [static files, images, etc.]
|
|-- .veritableingore
|
|-- index.md
|
|-+ Blog
| |-- Dogs.md
| |-- Update.md
| |-- Hello.md
|
|-+ About
| |-- About.md
We've already talked about the .veritable and src folders, as well as the .veritableingore file.
Let's talk about the other files and folders in this Veritable project.
This is the first file users will see when visiting your project's site.
When a folder only contains one non-hidden file, (in this case, the root [Project Name] folder containing the index.md file), Veritable will render this file instead of providing a list of all files in that directory.
You can name a file
index.[extension]to force this behavior if needed. Note, however, that this might make other files in the same folder inaccessible.
This folder contains a bunch of files.
When requested, it will show a list of all files it contains, in this case, the Dogs.md file, the Update.md file, and the Hello.md file.
When displaying these pages on the website, to the user, the extension will be stripped for clarity.
As mentioned before, when a folder only has one file, that file will be rendered. This is what we're doing with the About folder.
Because we're using an index file, other files in this directory are not listed.
Remember "You can name a file
index.[extension]to force this behavior if needed. Note, however, that this might make other files in the same folder inaccessible."?
A way to get around this is to wrap files with a folder. When you do this, the file will be visible as a section, and the user will be able to access it.
So far, Markdown, and RST files work as viable pages. Any other file type will be displayed as plain text in a monospaced font.
There are plans to add HTML and SMD documents in the future. If you happen to implement this, please open a pull request. :)
Let's say that we have a doggo.md file about dogs, and we want to display our own image of a doggo on that page (located in /src/doggo.jpg).
In markdown, we can use  to display images.
To display the image of the doggo, we'd put something like
in the doggo.md file.
You're probably already doing this to read this file, but in case you aren't, you can use:
To start your site on your localhost, cd to your project folder and type:
$ veritable run
It should then show something like:
$ veritable run
Running on http://localhost:5000/...
Then open your favorite browser, and go to the localhost link.
Tada 🎉.
That's about it for now. Have fun with Veritable!
Sincerely,
The Vertitable Project Authors
Now that you're done reading this, delete this file ('README.md'), and start your own project!
Oh, and here are all the veritable commands currently available:
| Command | Usage |
|---|---|
veritable init [project path] |
Start a new Veritable project in the CWD. |
veritable run |
Run your Veritable app. |
veritable configure [variable] |
Set a project variable, i.e. AUTHOR. |
Here are all the project variables that can be configured through the $ veritable configure [variable] command.
| Name | What it Does |
|---|---|
| AUTHOR | The author of the veritable website you're working on. |
| DESCRIPTION | Some text describing your website. |
| NAME | The name of your project |
This is a list of most terms used within the veritable project source code. (This isn't necessary know unless you're editing the source code yourself. )
Pages that can be displayed to the user:
endpoint: a page, file, source, or folder.page: an endpoint that renders styled content.raw: an endpoint that renders the contents of a file.source: a literal file (such as an image) to be embedded in a page.section: an end_point that renders the contents of a directory.
System specific vocabulary:
web_path: the path provided by the user.path: a system path.folder: a system folder.file: a system file.
What to call different people using the veritable project:
- user: a person using a Veritable website
- runner: a person making a Veritable project
- a Veritable Project author: a person working on The Veritable Project
the different uses of the word Veritable:
- a Veritable website: a veritable project rendered as a website through the veritable project.
- a Veritable project: series of folders/files created by a runner.
- The Veritable Project: the veritable project source code/tool.