Documentation | Larammerce

# Documentation

Documentation
References

This article is a complete guide to writing documents for the larammarce project.
Larammerce documentation is composing with markdown syntax ¹.also initial knowledge of git commands ² is necessary.

# Starting point

If this is your first contribution, follow instructions composed on contributing (opens new window) article on larammerce.com (opens new window).

# Requirements

Tool name	Version(distro)
Operating system	Every version of windows,Osx, linux supporting installation of Node.js
Node.js	V16 or higher

NODE version support :

Consider that this project integrates well only with Node.js version 16.

You can Install Node.js here (opens new window).

In order to use different Node.js versions, install `nvm` or `direnv` following description below:

Install nvm (opens new window)
nvm is a tool which gives you the ability to switch between different versions of Node depends on project's requirements.

Install direnv (opens new window)
You can set an environment variable to enable legacy mode by creating a file named .envrc on .gitignore directory including code below :

export NODE_OPTIONS=--openssl-legacy-provider

# Overall structure

Each document must consist of the following parts:

1) Introduction
Describe the overall view of the page by writing a general illustration of the represented subject.

2) Technical description
Write technical details based on markdown structure.

2) Sum Up
Make a brief review of the parts above (optional) and write the page references.

# How to write sections and subsections

Write the article title using h2 tag and h3 ,h4 ,..., h6 for the subsections.

NOTE:

Overusing these tags makes the sidebar crowded and complicated.
Only h2 and h3 headers get indexed in the right sidebar as the table of contents.
Avoid h1 Header. The usage of h1 header is not permitted in Larammerce documents.

EXAMPLE

## Documentation
[[toc]]
...
This article ... is necessary.
...

### Overall Structure
...
Each document must consist... parts.
...

#### How to write sections and subsections

1
2
3
4
5
6
7
8
9
10
11
12

# How to describe life cycles and road maps

In order to visually describing the details of a procedure or showing a map or a diagram, Draw a schema following these 2 steps:

Upload the schema on vuepress\public directory.
Use Markdown syntax to upload it on your .md file.

Consider the example below:

road map sample

Avoid Windows Paint!

'Windows Paint' is not suitable for this purpose.

# How/When to put the notices, warnings, and danger zone sections

You can use it when you want to get your readership's attention.

PATTERN

:::tip title-of-notice
text-of-notice
:::

1
2
3

EXAMPLE

:::tip NOTE
This function checks the activation of the representative management section.
:::

1
2
3

OUTPUT

NOTE

This function checks the activation of the representative management section.

NOTE: Tip can be replaced (according to your purpose and situation) with warning, danger, notice or success after three colon signs.

# How/When to add tables

To represent a list in a nice configuration with ordered alignment use tables.

Consider that tables should Have:

Organized alignment
Clear content
Container width (never exceed the page width)
Suitable amount of columns

NOTE: Avoid using a table when there are many explanations or a code sample.

# How to present the paths and directories

To write paths hierarchical structure from the main directory to subdirectories follow description below:

|---main directory
    |---sub directory1
    |---sub directory2
        |---sub of sub direcroty2

1
2
3
4

NOTE: You can add some optional descriptions in parentheses.

EXAMPLE

|--- .vuepress/ (dir)
    |--- styles/ (dir)
        |--- index.styl (styl file)

1
2
3

# How to present the file names (Addressing the project files)

Addressing files is applicable in many parts of a document. writing the path between grave signs is the right way to represent the address through a text.

EXAMPLE:

`/path/to/your/docs/.vuepress/theme/styles/custom-blocks/styl`

In order to create a new custom block you can modify the file /path/to/your/docs/.vuepress/theme/styles/custom-blocks/styl.
To show the path use commenting on the top of the commands.

//root address: .vuepress/theme/styles/custom-blocks/styl
&.success
    background-color rgba(80,153,61,.3)
    border-color darken(#50993d, 35%)
    color darken(#50993d, 70%)
    .custom-block-title
      color darken(#50993d, 50%)
    a
      color $textColor

1
2
3
4
5
6
7
8
9

# How to present the variables and technical words

Variables and technical words must be placed inside double graves.

EXAMPLE

Run this project on your `local host`, `port:8080`.

OUTPUT

Run this project on your local host, port:8080.

# How to describe the methods and classes

Methods and classes should be described following the pattern below:

// app/Models/User.php
class User extends BaseModel{
    ...
    private int $id; // This attribute keeps the user's primary key
    ...
}
function test(string $input){
    ...
    return true; // if $input=="1"
    ...
}

1
2
3
4
5
6
7
8
9
10
11

NOTE: Dots mean you have more codes previously and thereafter.

# How to write code blocks

To do so, use 3 graves to create a code block and use labels showing what syntax are you using.

EXAMPLE

code blocks:image

OUTPUT :

this is a bash code block sample

function test(string $input){
    ...
    return true; // if $input=="1"
    ...
}

1
2
3
4
5

&.success
    background-color rgba(80,153,61,.3)
    border-color darken(#50993d, 35%)

1
2
3

# Where to put video blocks

better to put the video block at the lowermost part of the document, before the reference section. to upload a video on your .md file follow description below:

Copy the video iframe code.
Paste it at the bottom of your document

<iframe src="video iframe code "  allowFullScreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"></iframe>

# How to write the page references

In order to link a word or a part of the article to a website, you should mention it as a reference following structure below:

Hyperlink the specific part and give it a superscript so the user can find it in your article. (this is an internal link, redirects you to the reference section)

*the specific word or sentence* *<sup>[1](#1)</sup>*

Now use this command to build your reference.

*1.<a name="1">[write whatever you want](put the link here )</a>*

# How to put links to other documents

Each section in a Larammerce document has a title on which you can hold the mouse to see the sharp sign at the left side . Clicking on this sign will show you the url address of this section which can be used to create a link to that section into your document.

Hover on the considered title.
copy the url.
paste url in the pattern below:

[expression](url address)

NOTE: If your desired topic has been already composed before in another Larammerce document, refrence the topic to the section or the whole document.

# How to show the code block outputs

Here is an example on how to show the hello world output script :

function test_function(string $input){
    ...echo "hello world"
    return...
}

1
2
3
4

php script.php
# output: hello world

1
2

# How to show an HTTP request and its response

To do so, you can call an API:

fetch localhost:8080/api/v1/some/test/api

OUTPUT :

{
  "keyA": "valueA",
  "keyB": "valueB",
  "keyT": ["item1", "item2"]
}

1
2
3
4
5

# How to put links to other websites

There are 2 ways for it:

Create a notice section.
Bring it to the reference section.

NOTE: It should have an independent container and should not be inside a paragraph describing other subjects.

# How to present theoretical concepts inside MD files

Representing a theoretical concepts might be complicated, inexplicable or have long explanations . The solution is designing and embedding appropriate related images. NOTE: upload the pictures on /path/to/your/docs/.vuepress/public/ directory and show it on your document composing code format below:

![image-subject](/image-file-name)

Working with a complicated dashboard can cause many misunderstandings among users. to avoid upcoming problems, you can use a schema or a snapshot of the specific part you considered.

NOTE: the screenshot should not contain your tabs and all your computer environment.

# a quick sum-up on picture usage rules

Where to Use the Images ?

You are allowed to embed an image into the Larammerce document only in 3 situations :

1. To define some parts of admin panel that is difficult to understand .

2. To describe a difficult technical concept .

3. To illustrate a road map or life cycle or diagram .

# References

1. What is markdown ? (opens new window)
2. How to work with git ? (opens new window)

# Video source

← Contributing Support →

# Documentation

# Starting point

# Requirements

# Overall structure

# How to write sections and subsections

# How to describe life cycles and road maps

# How/When to put the notices, warnings, and danger zone sections

# How/When to add tables

# How to present the paths and directories

# How to present the file names (Addressing the project files)

# How to present the variables and technical words

# How to describe the methods and classes

# How to write code blocks

# Where to put video blocks

# How to write the page references

# How to put links to other documents

# How to show the code block outputs

# How to show an HTTP request and its response

# How to put links to other websites

# How to present theoretical concepts inside MD files

# How to present the technical subjects related to the admin dashboard

# a quick sum-up on picture usage rules

# References

# Video source