This repository contains the source of the Sigasi documentation. You can find the rendered version at https://insights.sigasi.com
We are using markdown with Hugo.
- Install: Hugo
- Build
hugo
- Test:
hugo server --buildFuture --buildDrafts
to start serving pages locally. The url will be printed in thehugo
output.- Use the
-F
(or--buildFuture
) option to show posts with dates in the future. - Use the
-D
(or--buildDrafts
) option to show posts with draft status.
- Use the
- Tools:
- Enable shell autocompletion:
sudo hugo gen autocomlete
- Enable shell autocompletion:
- Create content based on archetypes:
- New release notes:
hugo new content/releasenotes/sigasi-4.06.md
- New tech article:
hugo new content/tech/fancy-title.md
- New release notes:
- External link:
[text](http://www.example.com)
- Internal link:
[text]({{< ref "/manual/demo" >}})
- title as text:
{{< page "manual/demo" >}}
- title as text:
- Link with link text:
<https://www.sigasi.com>
- Use dashes as separator. E.g.:
test-me.md
and nottest_me.md
- Images are stored in an
img
folder (e.g./img/opinion/...
,/img/tech/...
, ...) - Image file names must be lower case
Tips:
- Images can be aligned by using the
figure
shortcode withclass
argument, e.g.{{< figure src="/img/xxx" alt="alt text" class="uk-align-right" >}}
- When adding a
link
to a figure, it becomes clickable. When the link is an image (e.g. same as the src), a lightbox is used to show the image.
Tips:
- You can specify the language of code blocks by appending the language to the first three back ticks: e.g.
entity example is
port(
clk : in std_logic
);
end entity;
Syntax highlighting is configured as follows:
- Added 2 config settings to config.toml
- to allow code blocks like above automatically be highlighted:
pygmentsCodeFences = "true"
- to use a separate css file:
pygmentsUseClasses = "true"
- to allow code blocks like above automatically be highlighted:
- Included a new css file
syntax.css
inlayouts/_default/baseof.html
which is generated using the commandhugo gen chromastyles --style=monokai > static/css/syntax.css
- In case you want to change the style, different styles are available, check https://xyproto.github.io/splash/docs/all.html
- More Hugo documentation on highlighting: https://gohugo.io/content-management/syntax-highlighting/