Skip to content

Latest commit

 

History

History
64 lines (49 loc) · 2.19 KB

about-this-repo.adoc

File metadata and controls

64 lines (49 loc) · 2.19 KB

Some guidance about working this repo

Folder structure

  • document should be structured in sections as it can be reused easily by hugo

  • images should be placed locally within the sections

  • if there are very many images, it is recommended to create an images folder

  • all documentation and image content must be placed in folder docs

  • folder hugo contains just additional rending meta data for HUGO

  • use readme.adoc just for rendering in code.siemens.com. These files should just contain includes but no content

  • use index.adoc just for rendering in hugo. These files should just contain includes but no content.

Warning
 all sections must start with level 3 heading # 
│
├── docs/                               # the documentation content
│   ├── <sectionX>/
│   │   ├── images                      # if there are many images, put them into a folder
│   │   │   ├── ...
│   │   ├── <chapterY>.adoc             # starting with level 3 heading
|   |   ├── readme.adoc                 # for code.siemens.com rendering.
|   |                                   # May inlude level 2 heading and icludes all files from this folder
│   ├── <pdf-index-document>.adoc       # index adoc file(s) for PDF documents
|
├── hugo/                               # HUGO rendering of docs (optional)
│   ├── <sectionX>/
│   │   ├── _index.adoc                 # HUGO metadata to render sectionX

Howto to test and run Documentation locally

init / update to latest version

git submodule init
git submodule update --recursive --remote

submodule deinit before commit

git submodule deinit -f --all

download gohugo, run

# workaround:
hugo mod init ugly-dummy

hugo -v -d ./build server

# or
hugo -v --config ./config.toml --themesDir ./themes --contentDir ./docs -d ./build server

# go run main.go -v --config ../../prototypes/hugo_asciidoc_ddd/config.toml --themesDir ../../prototypes/hugo_asciidoc_ddd/themes --contentDir ../../prototypes/hugo_asciidoc_ddd/docs -d ../../prototypes/hugo_asciidoc_ddd/build server
# go test -v ./markup/asciidoc/