University department website

[epogrebnyak]

We are in process of adapting Doks for a university department website, will soon post.

Things trying to achieve:

• Russian/English version (so far a document layout breaks if no corresponding English version)
• alternative content structure (not just content/docs)
• "open book" layout (no landing page, directly to docs, but in retrospect landing is a good solution)
• getting non-tech writers to use markdown and the theme

We are into reviewing alot of Hugo concepts while doing this - together with with @necelentano.

Will post link soon once we are past the draft. Hope this can be useful to beginers and other authors.

[epogrebnyak]

A rough draft is https://necelentano.github.io/finec-mgimo-v2/

[epogrebnyak]

@h-enk, thanks for explaination - the View next was hiding it - I would have written back ealier is I saw it.

Maybe explaining point of confusion can help, so I will write things I still do not understand:

• what does "contains Doks as a npm dependency" mean? both starter and child seem to have package.json - which for my eye qualifies them quite similar (kind of "aha - it is some npm thing")
• next you write both child theme and the starter theme can run npm update - which confuses even more - if it is same bahavior, that why bother with child vs starter is next thought
• in "contains Doks as a npm dependency" unclear what part of Doks is packaged - layouts? something else too?

Perhaps the key is this:

P.S. (2) If using the Doks child theme, the parent theme lives in ./node_modules/@hyas/doks/ and the child theme in ./. Child theme files override parent theme files.

My starting point is - here is a the Hugo direcotry structure - with Doks we have populated layouts (and the assets - ?) which enables to provide this beautiful view of rendered docs.

I feel there something quite trivial missing from my understanding, but I cannot quite guess what it is. Maybe the question are:

• what exactly makes Doks theme (what directories) - so it will be easier to understand what is packackaged
• what is npm responsible for starter theme?
• what is npm responsible in child theme?

Any information on these directions would be highly appreciated.

[epogrebnyak]

Looking at package.json - "doks-child-theme" depends on "@hyas/doks", ok, but how does ./node_modules/@hyas/doks/ get propagated to ./?

[h-enk]

Looking at package.json - "doks-child-theme" depends on "@hyas/doks", ok, but how does ./node_modules/@hyas/doks/ get propagated to ./?

I'm making use here of Hugo's mounts functionality — set in ./config/_default/config.toml:

[module]
  [[module.mounts]]
    source = "node_modules/@hyas/doks/archetypes"
    target = "archetypes"
  [[module.mounts]]
    source = "node_modules/@hyas/doks/assets"
    target = "assets"
#  [[module.mounts]]
#    source = "node_modules/@hyas/doks/content"
#    target = "content"
  [[module.mounts]]
    source = "node_modules/@hyas/doks/data"
    target = "data"
  [[module.mounts]]
    source = "node_modules/@hyas/doks/layouts"
    target = "layouts"
  [[module.mounts]]
    source = "node_modules/@hyas/doks/static"
    target = "static"
  [[module.mounts]]
    source = "node_modules/flexsearch"
    target = "assets/js/vendor/flexsearch"
  [[module.mounts]]
    source = "node_modules/katex"
    target = "assets/js/vendor/katex"
  [[module.mounts]]
    source = "assets"
    target = "assets"
  [[module.mounts]]
    source = "static"
    target = "static"
  [[module.mounts]]
    source = "content"
    target = "content"
  [[module.mounts]]
    source = "layouts"
    target = "layouts"
  [[module.mounts]]
    source = "archetypes"
    target = "archetypes"
  [[module.mounts]]
    source = "data"
    target = "data"

[h-enk]

what does "contains Doks as a npm dependency" mean? both starter and child seem to have package.json - which for my eye qualifies them quite similar (kind of "aha - it is some npm thing")

significant npm packages	Starter	Child
hugo-bin	yes	yes
@hyas/doks	no	yes

next you write both child theme and the starter theme can run npm update - which confuses even more - if it is same bahavior, that why bother with child vs starter is next thought

The command npm update is in both cases the same, but what is updated differs (see the table above).

in "contains Doks as a npm dependency" unclear what part of Doks is packaged - layouts? something else too?

The npm module @hyas/doks contains all of the h-enk/doks GitHub repository — they hold exactly the same.

[epogrebnyak]

  [[module.mounts]]
    source = "assets"
    target = "assets"

This seems a redefinition? Or some default?

[epogrebnyak]

Aha, now I see the perspective! вт, 15 июн. 2021 г., 9:11 Henk Verlinde ***@***.***>:

…

Looking at package.json - "doks-child-theme" depends on ***@***.***/doks", ok, but how does .***@***.***/doks/ get propagated to ./? I'm making use here of Hugo's mounts functionality <https://gohugo.io/hugo-modules/configuration/#module-config-mounts> — set in ./config/_default/config.toml: [module] [[module.mounts]] source = ***@***.***/doks/archetypes" target = "archetypes" [[module.mounts]] source = ***@***.***/doks/assets" target = "assets" # [[module.mounts]] # source = ***@***.***/doks/content" # target = "content" [[module.mounts]] source = ***@***.***/doks/data" target = "data" [[module.mounts]] source = ***@***.***/doks/layouts" target = "layouts" [[module.mounts]] source = ***@***.***/doks/static" target = "static" [[module.mounts]] source = "node_modules/flexsearch" target = "assets/js/vendor/flexsearch" [[module.mounts]] source = "node_modules/katex" target = "assets/js/vendor/katex" [[module.mounts]] source = "assets" target = "assets" [[module.mounts]] source = "static" target = "static" [[module.mounts]] source = "content" target = "content" [[module.mounts]] source = "layouts" target = "layouts" [[module.mounts]] source = "archetypes" target = "archetypes" [[module.mounts]] source = "data" target = "data" — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#320 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGWBLRDNGV2AO5EV4EKNVDTS3VJ3ANCNFSM46JMTYHQ> .

[h-enk]

@epogrebnyak, thanks for asking these questions! Major input for clarifying things — also for others, hopefully 😉

[epogrebnyak]

@h-enk - thanks for taking time to answer in detail.

My mind-model as of now it below.

Relation to hugo and npm:

• doks is a beautifil theme for hugo
• it uses hugo direcotry structure
• your markdown content is in content folder
• serverl other folders are responsible layout and, as above, the beautiful look of doks (which ones, to be precise?)
• these folders need to rely on javascript packages and libraries
• to update these packages and libraries you need npm manager

Extra benefits of npm:

• with npm you can also manage installagion of hugo - that is an added benefit
• npm allows you to customise scritpts that you use often this is npm run <something> command

Starter theme:

• the original option for doks project is called starter theme
• this where development of doks theme goes
• if you cloned this starter theme and something was changed later, you may need manual steps to update your project
• however starter theme is good if you want to experiment and add something to the theme your self
• beware again, updating with fresh version of theme may need manual actions - you have to be good with git for this

Child theme:

• some users want just a few changes in layout and want the updates and corrections on doks theme downloaded
• this usecase is similar to git submudule for the Hugo themes, but submodule is a pain and we have a luxury of npm manager
• hugo allows to "mount" direcotries to another locations, this functnality is used in child theme
• (to be continued here)
• names starter and child may mislead - a starting user you may want a child theme if pallng few changes to a theme, so it pays off under their contruction and internals

[h-enk]

@epogrebnyak, thanks for this. Will get back on this later — bit busy right now.

[epogrebnyak]

Here our latest for faculty webpage - will be available soon at finec.mgimo.ru

[epogrebnyak]

Yes, we are live at https://finec.mgimo.ru

[h-enk]

@epogrebnyak, nice — I think the first Doks site that is multilingual! You're OK with me adding the site to Showcase?

[h-enk]

@epogrebnyak, I noticed you have some Content Security Policy issues. I think (using Laboratory) you can fix them, by making sure these are in:

default-src 'none'; font-src 'self'; frame-src https://player.vimeo.com https://www.youtube.com; img-src 'self' https://img.shields.io https://mgimo.ru; script-src 'self'; style-src 'self' 'unsafe-inline'

[h-enk]

@epogrebnyak, re. search, does this help you: #310 (reply in thread)

[epogrebnyak]

@h-enk - thank you for looking up the site and suggestions, will try to fix. Something we have not figured out yet well yet - how to make a switch that works if we have fewer pages in one than another. Right now we have to mirror a page in 'en' if we have it in 'ru' - otherwise our homegrown switch breaks. We filled issue here at project repo: finec-mgimo/finec-mgimo.github.io#95 ср, 14 июл. 2021 г. в 10:16, Henk Verlinde ***@***.***>:

…

@epogrebnyak <https://github.com/epogrebnyak>, re. search, does this help you: #310 (reply in thread) <#310 (reply in thread)> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#320 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGWBLXNA7RFKZAOXWEUMPLTXU2WJANCNFSM46JMTYHQ> .