Regarding project "Refactor and Automate Infusion Documentation"

Yash Jipkate yashjipkate at gmail.com
Wed Mar 18 07:59:40 UTC 2020


Hi Justin,

I wanted to know how is the current site hosted. I am currently writing my
proposal and I need to know the current method of deployment so I can
search about how to deploy HUGO on it and write about it in my proposal.

Thanks
Yash

On Mon, Mar 16, 2020 at 9:00 PM Justin Obara <obara.justin at gmail.com> wrote:

> I guess it’s something we can discuss and you can add to your proposal.
> It’s something I would have to think about more, but we could look into
> solving this through convention, or look into if there is a common front
> matter that makes sense to include.
>
> Thanks
> Justin
>
> On Mar 16, 2020, at 11:21 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>
> Hi Justin,
>
> I noticed that in the current setup we use front matter to specify the
> title of the page. But since we need to migrate all SSG related data, this
> would mean that front-matter should not be present in the content files.
> But not all titles can be automated in pre-configured front-matter. For
> example, MInimalFootprint.md
> <https://github.com/fluid-project/infusion-docs/blob/master/src/documents/tutorial-prefsFrameworkMinimalFootprint/MinimalFootprint.md> has
> the title 'Preferences Framework: Minimal Footprint' which can not be
> referred from its filename as was my plan for possible automation. Should
> we allow the title in the front matter in the content repo? I personally
> suggest that we should keep it since irrespective of the framework used,
> the title is something that is common to all SSGs' front-matter.
>
> What do you think about it?
>
> Thanks
> Yash
>
>
> On Thu, Mar 12, 2020 at 7:22 PM Justin Obara <obara.justin at gmail.com>
> wrote:
>
>> Hi Yash,
>>
>> Sounds good.
>>
>> Thanks
>>
>> On Mar 12, 2020, at 9:27 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>>
>> Hi Justin,
>>
>> I too think that we might have gone too deep into implementation details.
>> I will try to keep my discussion to immediate doubts and parts of the
>> codebase that I am facing difficulties with. Thanks for pointing out.
>>
>> Thanks.
>> Yash
>>
>>
>> On Thu, Mar 12, 2020 at 5:39 PM Justin Obara <obara.justin at gmail.com>
>> wrote:
>>
>>> Hi Yash,
>>>
>>> Please see replies below
>>>
>>> Thanks
>>> Justin
>>>
>>> On Mar 12, 2020, at 2:06 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>>>
>>> Hi Justin,
>>>
>>> I have replied inline, I also had some questions regarding the project.
>>>
>>>    - What is the current method of deployment of the docs? There are
>>>    lines like this
>>>    <https://github.com/fluid-project/infusion-docs/blob/05bba0b6e2509241b13d4b5c50656914b1e30314/src/layouts/default.html.handlebars#L64> in
>>>    the infusion-docs repo that uses relativeUrl to access something not
>>>    included in the repo. From what I understand from the urijs docs,
>>>    relativeUrl gets the relative URL of the argument w.r.t the current URL.
>>>    But there is no such folder in the repo. In the link that I mentioned, the
>>>    path is of the main infusion repo which is hosted somewhere else. How is
>>>    the relative URL working if they are hosted differently?
>>>
>>> It looks like they are being copied to the correct location by the
>>> copyDeps
>>> <https://github.com/fluid-project/infusion-docs/blob/master/docpad.js#L69-L112> function
>>> in docpad.js. They are originally pulled in as dependencies listed in the
>>> package.json
>>> <https://github.com/fluid-project/infusion-docs/blob/master/package.json#L15-L32>
>>>  file.
>>>
>>
>> It seems that it is a way of managing external dependencies. I found this
>> blog <https://janaksingh.com/blog/hugo-package-management-folder-mounts/> that
>> describes how to do this in HUGO.
>>
>>>
>>>    - Since the migration is not incremental, how should this be carried
>>>    out? I cannot modify the structure of the documents to HUGO-friendly and
>>>    expect DocPad to keep running. One way to make this happen is to have a
>>>    fork of the docs repo and then carry out the modifications there and merge
>>>    it only when it is in a deployable state, i.e. when the HUGO repo is also
>>>    ready. What do you think?
>>>
>>> Yes, you should be doing your work in a separate branch. It probably
>>> makes sense to start off with some mock content, that is something small to
>>> work with to get the pieces sorted out.
>>>
>>
>> So, I would make a smaller version of the docs website with just a few
>> docs and complete it with the corresponding HUGO code as well and then add
>> the rest of the docs.
>>
>>>
>>>    - Do we change the design of the site? There are many good themes
>>>    available on HUGO which are ready to use. We can use them for the site and
>>>    would give it a new look. If we don't change the design of the site then a
>>>    custom theme needs to be built from scratch.
>>>
>>> I think for now expect that we’ll keep the same site design, but this is
>>> something that can be discussed and researched as well.
>>>
>>>
>>> Thanks.
>>> Yash
>>>
>>>
>>>
>>>
>>> On Wed, Mar 11, 2020 at 6:15 PM Justin Obara <obara.justin at gmail.com>
>>> wrote:
>>>
>>>> Hi Yash,
>>>>
>>>> As usual comments below.
>>>>
>>>> Thanks
>>>> Justin
>>>>
>>>> On Mar 10, 2020, at 3:05 PM, Yash Jipkate <yashjipkate at gmail.com>
>>>> wrote:
>>>>
>>>>
>>>> Hi Justin,
>>>>
>>>> Responded inline.
>>>>
>>>> Thanks.
>>>> Yash
>>>>
>>>>
>>>> On Tue, Mar 10, 2020 at 9:52 PM Justin Obara <obara.justin at gmail.com>
>>>> wrote:
>>>>
>>>>> Hi Yash,
>>>>>
>>>>> Comments below.
>>>>>
>>>>> Thanks
>>>>> Justin
>>>>>
>>>>> On Mar 10, 2020, at 11:40 AM, Yash Jipkate <yashjipkate at gmail.com>
>>>>> wrote:
>>>>>
>>>>> Seems like the previous mail got sent in plain text mode. Therefore,
>>>>> the hyperlinks vanished. I am sharing the links below.
>>>>>
>>>>>
>>>>>    - Archetypes in HUGO
>>>>>    <https://gohugo.io/content-management/archetypes/>
>>>>>    - Angular <https://angular.io/docs> and React
>>>>>    <https://reactjs.org/docs/getting-started.html> docs
>>>>>    - Static file management in HUGO
>>>>>    <https://gohugo.io/content-management/static-files/>
>>>>>
>>>>>
>>>>> Thanks.
>>>>> Yash
>>>>>
>>>>>
>>>>> On Tue, Mar 10, 2020 at 8:57 PM Yash Jipkate <yashjipkate at gmail.com>
>>>>> wrote:
>>>>>
>>>>>> Hi Justin,
>>>>>>
>>>>>> I have left some comments inline. Also, I'll be sharing the draft
>>>>>> proposal soon.
>>>>>>
>>>>>> Thanks.
>>>>>> Yash
>>>>>>
>>>>>>
>>>>>> On Tue, Mar 10, 2020 at 5:37 PM Justin Obara <obara.justin at gmail.com>
>>>>>> wrote:
>>>>>> >
>>>>>> > Hi Yash,
>>>>>> >
>>>>>> > I’ve left some more comments below.
>>>>>> >
>>>>>> > Thanks
>>>>>> > Justin
>>>>>> >
>>>>>> > On Mar 10, 2020, at 2:21 AM, Yash Jipkate <yashjipkate at gmail.com>
>>>>>> wrote:
>>>>>> >
>>>>>> > Hi Justin,
>>>>>> >
>>>>>> > Thanks for the reply. I have responded inline.
>>>>>> >
>>>>>> > Also, since the student application period approaches, should I
>>>>>> start on my draft proposal using HUGO as the SSG? Since I have found it as
>>>>>> the best alternative till now. If we find any other better alternative,
>>>>>> then we can switch. But according to me, HUGO is best suited for our needs.
>>>>>> >
>>>>>> >
>>>>>> > This would be up to you. You’re welcome to propose what you think
>>>>>> is best. You might want to consider adding steps for investigation,
>>>>>> experimentation and leaving things open to change.
>>>>>> >
>>>>>> >
>>>>>> > Thanks.
>>>>>> > Yash
>>>>>> >
>>>>>> >
>>>>>> > On Tue, Mar 10, 2020 at 4:26 AM Justin Obara <
>>>>>> obara.justin at gmail.com> wrote:
>>>>>> >>
>>>>>> >> Hi Yash,
>>>>>> >>
>>>>>> >> Some comments inline below.
>>>>>> >>
>>>>>> >> Thanks
>>>>>> >> Justin
>>>>>> >>
>>>>>> >> On Mar 9, 2020, at 4:32 PM, Yash Jipkate <yashjipkate at gmail.com>
>>>>>> wrote:
>>>>>> >>
>>>>>> >> Hi Justin,
>>>>>> >>
>>>>>> >> Thanks for the reply. I have responded inline.
>>>>>> >>
>>>>>> >> Thanks
>>>>>> >> Yash
>>>>>> >>
>>>>>> >>
>>>>>> >> On Mon, Mar 9, 2020 at 6:51 PM Justin Obara <
>>>>>> obara.justin at gmail.com> wrote:
>>>>>> >>>
>>>>>> >>> Hi Yash,
>>>>>> >>>
>>>>>> >>> Somewhere along the line we lost our CC to the fluid-work mailing
>>>>>> list. I’ve added that back in now so that others can follow along and
>>>>>> provide input as needed.
>>>>>> >>>
>>>>>> >>> Another tool to look at would be https://docusaurus.io. It would
>>>>>> be good to also investigate if there are other options/solutions that we
>>>>>> haven’t yet mentioned.
>>>>>> >>
>>>>>> >>
>>>>>> >> A complete list of all the major static site generators can be
>>>>>> found at StaticGen. The list is sorted on the basis of recent trends in the
>>>>>> community. Regarding Docusaurus, I found this blog that compares HUGO and
>>>>>> Docusaurus. There is also this comment in an issue that compares Jekyll,
>>>>>> Docusaurus, and HUGO. I read the Docusaurus docs and there are some
>>>>>> advantages that it provides over the other SSGs.
>>>>>> >>
>>>>>> >> In-built versioning
>>>>>> >> Translations
>>>>>> >> Inbuilt search feature using Algolia.
>>>>>> >>
>>>>>> >> To summarize all the findings over the course of this thread, the
>>>>>> various SSGs and their details are:
>>>>>> >>
>>>>>> >> HUGO
>>>>>> >>
>>>>>> >> Written in Go, therefore fast build times - countered by the fact
>>>>>> that Go deprives us of npm packages and build times are not that big a
>>>>>> concern to us.
>>>>>> >> The search functionality needs to be manually implemented by the
>>>>>> ways described here.
>>>>>> >> Versioning can be realized by the usage of tags - inbuilt
>>>>>> provision for tag-specific pages.
>>>>>> >> Various themes to choose from, all cost-free.
>>>>>> >> Pre-defined convention for best practices.
>>>>>> >> Vast community support and one of the trending SSGs (according to
>>>>>> stars on the repo in the past week: source)
>>>>>> >>
>>>>>> >> 11ty
>>>>>> >>
>>>>>> >> Written in JS, access to npm packages.
>>>>>> >> No search functionality provided nor any documentation provided on
>>>>>> how to implement it. Its docs site uses Duck Duck Go search.
>>>>>> >> Versioning can be done by collections but not as intuitive as HUGO
>>>>>> tags - no tag-specific pages.
>>>>>> >> No provision for custom themes, need to start from scratch.
>>>>>> Although many third-party themes are available. No documentation on using a
>>>>>> custom theme as in HUGO.
>>>>>> >> Flexible in terms of conventions.
>>>>>> >> Good community support.
>>>>>> >>
>>>>>> >> Docusaurus
>>>>>> >>
>>>>>> >> Written in JS, access to npm packages.
>>>>>> >> In-built search functionality powered by Algolia.
>>>>>> >> In-built versioning functionality.
>>>>>> >> Only one theme available needs to be customized to change. Uses
>>>>>> React.
>>>>>> >> Rigid conventions. Uses React components to render and therefore
>>>>>> can not modify much in its default way of rendering.
>>>>>> >>
>>>>>> >> Absence of page-level variables, and therefore would cause
>>>>>> difficulties when the SSG metadata is not allowed in the MD files. Not
>>>>>> suited for our use case.
>>>>>> >>
>>>>>> >> Good community support, backed by Facebook.
>>>>>> >>
>>>>>> >> Clearly, we can't use Docusaurus. I took a look at Hexo and it had
>>>>>> similar problems and has weak documentation. Similar goes for Docsify too.
>>>>>> It doesn't have variables and weak templating and I also found its
>>>>>> documentation less friendly. It can't be used for our requirements.
>>>>>> >>
>>>>>> >> This again puts me in favor of HUGO.
>>>>>> >>
>>>>>> >> Do you have any other suggestions?
>>>>>> >>
>>>>>> >>
>>>>>> >> Thanks for the research, feel free to look at others or other
>>>>>> setups that may inspire implementation.
>>>>>> >>
>>>>>> >>
>>>>>> >>>
>>>>>> >>> I’ve left some more comments below.
>>>>>> >>>
>>>>>> >>> Thanks
>>>>>> >>> Justin
>>>>>> >>>
>>>>>> >>> On Mar 8, 2020, at 1:16 AM, Yash Jipkate <yashjipkate at gmail.com>
>>>>>> wrote:
>>>>>> >>>
>>>>>> >>> Hi Justin,
>>>>>> >>>
>>>>>> >>> I just got a reply from the 11ty team on the issue that I opened.
>>>>>> 11ty has directory specific data files that can be used to define config to
>>>>>> be shared to all the lower levels. The major downside of this is that the
>>>>>> directory specific data file needs to be placed in the directory itself.
>>>>>> Therefore, the data file will be directly in between the content files.
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> You say that the data file can define configuration that can be
>>>>>> shared by lower levels. So you could have two levels of directories, one
>>>>>> that contains the data file and a directory of all the docs. In that way
>>>>>> you wouldn’t haven’t worry about mixing them together. But I’d have to see
>>>>>> how this looks in a more concrete example.
>>>>>> >>
>>>>>> >>
>>>>>> >> If I am getting it the right way, you are planning to have a
>>>>>> single data file. Yes, that would then nullify the point since we won't be
>>>>>> concerned with the mixing of just one data file. But in case of multiple
>>>>>> data files, say we want to customize some folders that should be different
>>>>>> from the other folders at the same level, then we would need different data
>>>>>> files in both the folders, and that's the kind of mixing that I'm concerned
>>>>>> with.
>>>>>> >>
>>>>>> >>
>>>>>> >> I was suggesting something like
>>>>>> >>
>>>>>> >> - Tutorials/
>>>>>> >> - data file
>>>>>> >> - pages/
>>>>>> >> - tutorial_example.md
>>>>>> >> - API
>>>>>> >> - data file
>>>>>> >> - pages/
>>>>>> >> - framework_api.md
>>>>>> >>
>>>>>> >> I’m not exactly sure what our needs would be in terms of
>>>>>> configuration in these files, do we actually need one per document file,
>>>>>> one per section, or just one overall. The above example assumes one per
>>>>>> section.
>>>>>> >
>>>>>> >
>>>>>> > Currently, we would need one configuration file per version. There
>>>>>> are three things that would be different on each page - the title, GitHub
>>>>>> edit link, and the version. This information would be normally provided via
>>>>>> the front-matter of the page but in our case, this can be provided in a
>>>>>> data file (or a shared template). The title and the GitHub link can be
>>>>>> generated from the name of the file using a variable but the version needs
>>>>>> to be provided as a tag. So this tag would need to be in the data file (or
>>>>>> the shared template) of the directory that houses it. This means that there
>>>>>> would be one data file per version and a global data file.
>>>>>> >
>>>>>> > The structure you laid out also does some mixing. The data file is
>>>>>> inside the contents folder which would contain all the MD files. In HUGO
>>>>>> this data file is totally outside of the contents folder. While this
>>>>>> doesn't have any significant performance effects, it is mainly a
>>>>>> convention-related issue. Because we would then be cloning the repo
>>>>>> 'tagwise' inside these folders. So do we want the cloned part directly in
>>>>>> between the SSG data files or do we want these two in separate folders, is
>>>>>> a matter of convention and developer ease. I would personally prefer having
>>>>>> these two separate. What is your take on this?
>>>>>> >
>>>>>> >
>>>>>> > I guess this all depends on what the directory structure looks like
>>>>>> in the SSG. It seems we might have directories for each tag/version and the
>>>>>> file could be in there, or possibly we might b able to source the
>>>>>> tag/version name from the path that the files are in.
>>>>>>
>>>>>>
>>>>>> I favor the tag-wise directory structure since that would help in
>>>>>> setting archetypes. I am not sure what do you mean by sourcing the tag
>>>>>> name, we would still need to clone tag-wise to detect the tag/version
>>>>>> name from the path, right? In that case, archetypes would do the
>>>>>> trick.
>>>>>>
>>>>>
>>>>> Maybe we’re talking about different things, I’ll wait to see what it
>>>>> looks like in your proposal.
>>>>>
>>>>> >
>>>>>> >
>>>>>> > Now that you mention the GitHub edit link, I don’t think tags are
>>>>>> going to work. The tag is frozen, so to speak. We may need to use branches
>>>>>> instead, or a combination of branches and tags. I don’t think it will
>>>>>> change your workflow much, or at all, though.
>>>>>>
>>>>>>
>>>>>> Yes, the tags are frozen, thanks for pointing that out. However, the
>>>>>> tags and branches are inconsistent. The branches are 1.9.x, 2.x.x, and
>>>>>> master, whereas the tags are v2.0.0 and v1.5.0. Also, would it be
>>>>>> sensible to have a GitHub edit link for older versions? I saw the
>>>>>> documentation for Angular and React, and both of them have their
>>>>>> documentation for older versions snapshotted and do not edit them. The
>>>>>> edit on GitHub button on the older versions' docs are either dead or
>>>>>> point to the current branch of the docs. Therefore, I suggest that we
>>>>>> follow the tag-wise classification since that is the most widely
>>>>>> accepted format. What do you think?
>>>>>>
>>>>>
>>>>> That’s an options, although I’d prefer not to have the link than to
>>>>> have a dead one. It would be nice to be able to change the documentation
>>>>> after the fact in case there was an error, typo, or missing information.
>>>>> I’m not sure how likely that is though.
>>>>>
>>>>> >
>>>>>> >
>>>>>> >>
>>>>>> >>>
>>>>>> >>> According to my plan, the content repo was to be cloned in the
>>>>>> SSG repo, so if 11ty is to be used then after the cloning we would need to
>>>>>> further copy the directory specific data files into respective folders to
>>>>>> make them useful.
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> I guess this should be counted as a downside for 11ty since this
>>>>>> extra copying operation would require an extra script to maintain and would
>>>>>> cause a closer coupling.
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> You’d still need some sort of script to do the cloning, so not
>>>>>> sure how much extra work it would be. Maybe I’m forgetting or missing
>>>>>> something with how you were planning to do the clone.
>>>>>> >>
>>>>>> >>
>>>>>> >> Ideally, there should be one script for one functionality, so
>>>>>> therefore I was thinking of a different script. And moreover, by a script,
>>>>>> I meant by the code - maintaining it would be an additional task
>>>>>> irrespective of whether it is in a separate file or not. Since it couples
>>>>>> the two repos very closely, the maintenance can be frequent. And yes,
>>>>>> cloning would be done through a script.
>>>>>> >>
>>>>>> >>
>>>>>> >> I think we talked about possibly having a config file in the
>>>>>> document repo that defined the parts or organization. It could also be that
>>>>>> they are organized in a specific way, example directories to categorize the
>>>>>> contents. We’d just need to know how to parse or place these directories
>>>>>> and not each individual file. In this case there is a contract on what the
>>>>>> incoming directory structure is, or instructions on how to move from one to
>>>>>> another. Something to think about.
>>>>>> >
>>>>>> >
>>>>>> > I thought that we wanted to separate all SSG related data from the
>>>>>> content repo - that would include the config file as well. And yes, we just
>>>>>> need to decide on the directory structure and the content would be placed
>>>>>> accordingly and the SSG can then render the content.
>>>>>> >
>>>>>> >
>>>>>> > The config file I meant here is something that would define the
>>>>>> structure of the content repo. The SSG repo would use this to know what
>>>>>> parts are what. It wouldn’t be something particular to a specific SSG,
>>>>>> there would need to be something in the SSG repo that translated it to it’s
>>>>>> own information. But having a consistent directory structure could possibly
>>>>>> be used in place of such a file.
>>>>>>
>>>>>>
>>>>>> The structure of the content repo would be determined by the way the
>>>>>> data files (archetypes) are stored. The directory hierarchy of the doc
>>>>>> files would be the same as I pointed out, and the other files would be
>>>>>> re-organized. I don't think there is a feature such as a config to
>>>>>> determine the directory structure. The directory structure needs to be
>>>>>> consistent with the config of the SSG because the theme and the
>>>>>> archetypes will be valid on a content structure that is similar to
>>>>>> itself. Please correct me if I got you wrong.
>>>>>>
>>>>>
>>>>> What I mean is that you’d have some document in the content repo that
>>>>> identifies it’s structure. The SSG repo, on importing in the content would
>>>>> use this to place the files in the locations that the SSG is
>>>>> expecting/needs them to be.
>>>>>
>>>>
>>>> The SSG does not identify the structure of the contents, it would
>>>> validate the structure against the structure it is provided by the
>>>> combination of templates and archetypes. If it finds a different structure,
>>>> then it won't apply the templates. We can think of it as CSS selectors. Say
>>>> we have two CSS selectors as '.body .div .p'  and '.body .div' and suppose
>>>> we have a <h1> inside <body><div> then we don't have a CSS selector for
>>>> '.body .div .h1'  so it won't give any errors but it would simply apply
>>>> '.body .div' properties to it. And so the directory structure would need to
>>>> be consistent between the two repos.
>>>>
>>>>
>>>> Thanks for the detailed explanation. I actually meant that you would
>>>> have to create something as part of your import script that read in the
>>>> config doc and placed the files and directories in the locations that are
>>>> needed for the SSG.
>>>>
>>>
>>> Ah, yes. The script would be configured to import the contents of the
>>> repo so that the imported documents are placed in their expected locations.
>>>
>>>>
>>>>
>>>>>
>>>>> >
>>>>>> > The directory structure of the contents (src/documents) need not be
>>>>>> changed except for the images directory which would be moved to the static/
>>>>>> or as a page resource if it needs some processing (one more point where
>>>>>> HUGO beats 11ty since 11ty doesn't have any image processing features).
>>>>>> >
>>>>>> > We want the documentation to be readable/previewable on GitHub.
>>>>>> That means that the URLs (e.g. links between documents, images, etc) would
>>>>>> need to work both on GitHub and in the SSG created site. This may involve
>>>>>> some translation of these URLs. In the current site we do some of this
>>>>>> translation for changing between .md and .html, for example.
>>>>>>
>>>>>>
>>>>>> The images which don't need preprocessing (like resizing) can be
>>>>>> served directly from the static directory by relative paths and
>>>>>> through server URLs (docs). The relative path method doesn't give
>>>>>> previews in GitHub, whereas the URL method should give since that
>>>>>> doesn't have to do anything with the content management system of
>>>>>> HUGO.
>>>>>>
>>>>>
>>>>> I’m not sure what you mean here, or at least I’m not sure how this
>>>>> addresses the issue of URLs working on both GitHub and the final site.
>>>>>
>>>>
>>>> Actually, if you follow the relative path method (i.e. if the image is
>>>> in static/images/image1.png then the relative path in HUGO would be
>>>> /images/image1.png) it would work correctly when HUGO renders it in HTML
>>>> but won't be available in GitHub preview. Whereas if you use the full URL
>>>> (i.e. https://<root-url>/images/image1.png) then we can see the
>>>> correct GitHub preview as well. The only condition is that the image needs
>>>> to already hosted on the server so that it can be tested in local
>>>> development because HUGO generates such URLs for all static files. Here I'm
>>>> talking in the context of the syntax of displaying an image in Markdown
>>>> i.e. ![alt-text](img-url/path).
>>>>
>>>>
>>>> The relative paths to images should work on GitHub. You can see the “Creating
>>>> a New Adjuster UI
>>>> <https://github.com/fluid-project/infusion-docs/blob/master/src/documents/tutorial-prefsFramework/CreatingANewAdjusterUI.md>”
>>>> markdown file from our repo as an example. The links between documents is a
>>>> bit harder because png GitHub you have to reference “.md” files and on the
>>>> site you’ll reference “.html” files. In our current site, you can see that
>>>> we transform the URLs to be correct when generating the site.
>>>>
>>>> It’s preferable for the links in GitHub to be self referential so that
>>>> if the website is down, or if you just clone the docs repo and use that
>>>> locally, the links still work. Also, if you are creating new docs or
>>>> modifying existing ones, you’ll be able to test that the URLs are working.
>>>>
>>>
>>> This is an issue with HUGO that it doesn't render the images when
>>> relative URLs are used. I have opened a ticket
>>> <https://discourse.gohugo.io/t/how-to-render-image-in-github-markdown/23951/2> in
>>> the support forum of HUGO. I also saw some previous
>>> <https://discourse.gohugo.io/t/image-path/1721> tickets
>>> <https://discourse.gohugo.io/t/is-there-a-way-to-control-markdown-images-in-hugo/6687/4>
>>>  related to this topic. I got a reply from the team in which he gave me
>>> a link to one of his projects
>>> <https://github.com/bep/portable-hugo-links> where he achieved this. In
>>> HUGO there is a feature where we can convert a page into a bundle (like in
>>> the repo p1
>>> <https://github.com/bep/portable-hugo-links/tree/master/blog/p1> is
>>> converted to a bundle - by adding index.md) so the links would work both in
>>> preview as well as the site.
>>>
>>> We will have to make all those pages which are having images into
>>> bundles. This is done by having a directory with the name of the page and
>>> an index.md and the images in that directory. The import script would take
>>> the name of such MD files from the docs repo and make them into folder
>>> names and then import the images required into that directory. One way to
>>> conveniently carry this out would be to have these types of directories in
>>> the contents repo itself. Say, there is currently a doc *blog.md *which
>>> uses *img.png* stored in images/, we can re-organize this into a *blog* directory
>>> with *index.md *and the *img.png* in it. This way it would be easier to
>>> group the pages and their resources in one place and avoid unnecessary
>>> scripting and heavy coupling which would be vulnerable to breakage.
>>>
>>>
>>> I’m not sure if I’m not fully understanding the issue, but it doesn’t
>>> seem to be a problem or require a complex solution. For example it seems
>>> like images should work from an image directory under in the static
>>> directory ( https://discourse.gohugo.io/t/image-path/1721/3 ). Another
>>> way would be to use markdown render hooks
>>> <https://gohugo.io/getting-started/configuration-markup/#markdown-render-hooks>.
>>> Anyways, I wonder if we’re getting into too much specifics. It might be
>>> better to think of the end goal, and then think of how to get there with a
>>> few systems. Then you can compare the pros and cons. Perhaps this is what
>>> you are doing here with Hugo. I’m just saying that we shouldn’t get too far
>>> ahead with implementation details just yet.
>>>
>>
>> Actually, in the post you referred, the way he mentioned would only
>> display it in the rendered HTML. I have tried it for myself. The markdown
>> render hook method can also be looked upon. This method makes use of page
>> resources whereas the page bundle method renders the image just by
>> referring the relative path. I will look at the pros and cons of both the
>> methods and then decide on one.
>>
>>>
>>>
>>>>
>>>>> >
>>>>>> > The layout file in the layouts folder would be replaced by a
>>>>>> template layout file that is provided by the SSG. In the case of HUGO, this
>>>>>> can be achieved through themes, partials, and templates
>>>>>> > The static folder would be placed in static/ in the project root.
>>>>>> > I am not clear about what is the purpose of the ghpages-files
>>>>>> directory. In the deploy section of the README, it says that we don't use
>>>>>> GitHub pages to host. Then what is the use of this directory? Also, what
>>>>>> service do we currently use to host the site?
>>>>>> >
>>>>>> > There is some legacy in that we had originally used ghpages to host
>>>>>> the site, but moved to self hosting. We may move to a hosting service at
>>>>>> some point (e.g. back to ghpages, netlify, etc.). We should investigate
>>>>>> removing the ghpages-files directory.
>>>>>> >
>>>>>> >
>>>>>> >>
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> I am still inclined to HUGO because of our use case. Lesser
>>>>>> coupling, faster build times (since there are multiple steps like dispatch
>>>>>> and cloning and that would add to the build time) and a file structure
>>>>>> convention are some features that outperform 11ty. Some star features of
>>>>>> 11ty like multiple templates are not required by us since we use only MD
>>>>>> files.
>>>>>> >>>
>>>>>> >>> What do you think?
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> Addressing some of the comments/questions from earlier in the
>>>>>> thread. Not sure what the issue about Hugo being written in Go. Could you
>>>>>> explain and expand on that one more.
>>>>>> >>
>>>>>> >>
>>>>>> >> Being built in Go means it is deprived of the amazing features of
>>>>>> JS. Most importantly, the features of node and NPM which have many useful
>>>>>> packages. This has been the main concern of many developers.
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> Regarding flexibility. That’s not necessarily a bad thing. If we
>>>>>> maintain consistency in our use and follow best practices, I don’t think it
>>>>>> should be a matter for us and could mean that we can tailor it to our own
>>>>>> needs. If you know of a specific issue that 11ty’s flexibility is causing,
>>>>>> or could cause, it would be good to discuss it more.
>>>>>> >>
>>>>>> >>
>>>>>> >> If we are sure of maintaining best practices then this won't be
>>>>>> much of a problem. Actually, this was the case of AngularJS - it didn't
>>>>>> have a 'conventional' way of doing things and this resulted in a number of
>>>>>> bad practices. The new Angular then removed this by introducing a less
>>>>>> flexible framework. We can overcome this by setting up our own conventions
>>>>>> that would eliminate any bad practices that might pop up.
>>>>>> >>
>>>>>> >>
>>>>>> >> A contributing guide and documentation on usage, best practices,
>>>>>> conventions and etc. should be included with the project.
>>>>>> >
>>>>>> >
>>>>>> > Yes, that would be very important in deciding and cementing the
>>>>>> conventions.
>>>>>> >>
>>>>>> >>
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> Thanks
>>>>>> >>> Yash
>>>>>> >>>
>>>>>> >>> On Sat, Mar 7, 2020 at 11:59 PM Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>
>>>>>> >>>>
>>>>>> >>>> Hi Justin,
>>>>>> >>>>
>>>>>> >>>> I looked up 11ty more and found the following advantages over
>>>>>> HUGO:
>>>>>> >>>>
>>>>>> >>>> 11ty (2017) is newer than HUGO (2013).
>>>>>> >>>> 11ty is built using JavaScript whereas HUGO is built using Go.
>>>>>> JS being a native web language won't ever lose support whereas Go being a
>>>>>> third party might lose support.
>>>>>> >>>> 11ty has more flexibility regarding file extensions. It works
>>>>>> with formats other than MD as well.
>>>>>> >>>> 11ty has a flexible file system. So we can build it right from
>>>>>> the current file structure.
>>>>>> >>>> I also liked the documentation of 11ty compared to the one by
>>>>>> HUGO.
>>>>>> >>>>
>>>>>> >>>> But there is a major downside that since 11ty uses a flexible
>>>>>> directory structure, every page needs to have a front matter that specifies
>>>>>> the template it needs to use. HUGO being strict about directory structure
>>>>>> automates this process and is useful when we want to separate the content
>>>>>> from the front matter.
>>>>>> >>>>
>>>>>> >>>> I found this issue to fulfill our use case but it was closed
>>>>>> with a note stating it was solved in a version but I couldn't find any
>>>>>> documentation regarding it. Therefore I opened an 'education' type issue to
>>>>>> get their response.
>>>>>> >>>>
>>>>>> >>>> If this issue persists, then we might not be able to use 11ty
>>>>>> for our purpose.
>>>>>> >>>>
>>>>>> >>>> Thanks
>>>>>> >>>> Yash
>>>>>> >>>>
>>>>>> >>>> On Sat, Mar 7, 2020 at 12:28 AM Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>
>>>>>> >>>>> Hi Justin,
>>>>>> >>>>>
>>>>>> >>>>> Thanks for the reply. I have responded inline.
>>>>>> >>>>>
>>>>>> >>>>> Thanks.
>>>>>> >>>>> Yash
>>>>>> >>>>>
>>>>>> >>>>> On Thu, 5 Mar 2020, 7:02 pm Justin Obara, <
>>>>>> obara.justin at gmail.com> wrote:
>>>>>> >>>>>>
>>>>>> >>>>>> Hello Yash,
>>>>>> >>>>>>
>>>>>> >>>>>> Please see comments inline below.
>>>>>> >>>>>>
>>>>>> >>>>>> Thanks
>>>>>> >>>>>> Justin
>>>>>> >>>>>>
>>>>>> >>>>>> On Mar 5, 2020, at 2:43 AM, Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>>
>>>>>> >>>>>> Hi Justin,
>>>>>> >>>>>>
>>>>>> >>>>>> Just confirming whether you got my previous email. Is there
>>>>>> something I should add or elaborate on?
>>>>>> >>>>>>
>>>>>> >>>>>> Thanks
>>>>>> >>>>>> Yash
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>> On Tue, Mar 3, 2020 at 3:14 AM Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>>>
>>>>>> >>>>>>> Hi Justin,
>>>>>> >>>>>>>
>>>>>> >>>>>>> I will try to mark the issues on JIRA since it should have
>>>>>> only legitimate issues.
>>>>>> >>>>>>> Also, I tried out the repository communication. I created a
>>>>>> dispatcher repo and added a workflow to send a dispatch to another consumer
>>>>>> repo created by me. It worked perfectly and the repo was consuming the
>>>>>> event.
>>>>>> >>>>>>
>>>>>> >>>>>> How is the consumer repo affected by forks of the dispatcher
>>>>>> repo. That is, if I fork your dispatcher repo and push to it, will it send
>>>>>> a dispatch event to your consumer repo and trigger an action?
>>>>>> >>>>>>
>>>>>> >>>>>> It’s also worth investigating other methods that do not couple
>>>>>> the repos together so closely.
>>>>>> >>>>>
>>>>>> >>>>>
>>>>>> >>>>> No, the dispatch event does not work on forks. I forked the
>>>>>> dispatcher repo here and pushed to the main branch. This failed to trigger
>>>>>> the workflow in the main consumer repo (you can check here). Also forking
>>>>>> the consumer repo won't have any downside since the dispatch event demands
>>>>>> the name of the repo along with the owner so forks won't be affected.
>>>>>> >>>>>
>>>>>> >>>>> Another method I initially thought before discovering repo
>>>>>> dispatches was to have a special server for the sole purpose of sending and
>>>>>> receiving events that would trigger builds. This would allow us to have
>>>>>> custom features not limited by those offered by GitHub API. The downside is
>>>>>> that we would need to maintain an additional repo and would not be able to
>>>>>> access the community help that exists for GitHub's API. Also since out
>>>>>> needs are satisfied by the GitHub's API, we won't need any other custom
>>>>>> features than the ones already present.
>>>>>> >>>>>>>
>>>>>> >>>>>>> I think the design would not undergo much change. I saw the
>>>>>> official documentation page of HUGO and they use pretty much similar design
>>>>>> - a top nav, a side nav, and the main content.
>>>>>> >>>>>>>
>>>>>> >>>>>>> The source code is open-sourced here. I looked at the code
>>>>>> and saw that the menu bar items were hard-coded in a site-wide config file
>>>>>> here. The layout for the menu bars are placed in partials/ of the theme
>>>>>> that HUGO's site uses.
>>>>>> >>>>>>> To maintain the design of the current site, we would have to
>>>>>> make a custom theme of our own (similar to the theme used by HUGO docs).
>>>>>> >>>>>>> The structure of the files would also need to be changed
>>>>>> accordingly. The md files or the content files would be put under content/
>>>>>> and assets under static/.
>>>>>> >>>>>>>
>>>>>> >>>>>>> The repo would be essentially HUGO-oriented, with all the
>>>>>> folder structure conforming to the one required by HUGO. In case of
>>>>>> switching to another SSG, we would need to follow the folder structure and
>>>>>> the conventional best practices followed by that particular SSG. We would
>>>>>> again need a restructuring, although not this massive. Also, things like
>>>>>> menu bar items which would be in the root config of HUGO would also be
>>>>>> needed to migrate since the new SSG might have a different approach.
>>>>>> >>>>>>
>>>>>> >>>>>> Regarding the folder structure, couldn’t we just copy/import
>>>>>> the content to whichever location we wanted during that step of the
>>>>>> workflow. Do we have to mirror it in the content repo?
>>>>>> >>>>>
>>>>>> >>>>>
>>>>>> >>>>> Yes, that's exactly what I am proposing. I plan to re-organize
>>>>>> the folder structure and not mirror the current content to the new
>>>>>> structure.
>>>>>> >>>>>>>
>>>>>> >>>>>>> Splitting the docs and the HUGO code would deprive of the
>>>>>> many useful and core features of the tech. The front-matter or the
>>>>>> meta-data per page is of great use and can be used to greatly customize and
>>>>>> control the pages. Stripping HUGO of such important features could become a
>>>>>> problem in the future or even during this project. For example, the GitHub
>>>>>> link to edit the page is different on every page and can be stored in
>>>>>> front-matter. Also, if we wanted to add an 'author' or 'last updated'
>>>>>> information to the page, It would again be a front-matter thing.
>>>>>> >>>>>>
>>>>>> >>>>>> Can this information be automatically generated on import of
>>>>>> the content?
>>>>>> >>>>>
>>>>>> >>>>>
>>>>>> >>>>> We can have a common front matter template for all files in a
>>>>>> directory by the archetype feature of HUGO.
>>>>>> >>>>>>>
>>>>>> >>>>>>> Also, in case of switching SSG, the main part i.e. the MD doc
>>>>>> files would be in the same hierarchy of contents. The only change that
>>>>>> mostly happens in the names of the directories and some best practice
>>>>>> conventions. Therefore, in my opinion, we should not split the codebase
>>>>>> since it would be almost equal work switching in both cases but the
>>>>>> one-repo approach gives many more additional features, and this advantage
>>>>>> would be in other SSGs too.
>>>>>> >>>>>>> I took a look at some other SSGs like Jekyll and 11ty. Most
>>>>>> of my findings were the same as those by Sachin. One of the main drawbacks
>>>>>> of Jekyll is build time increases exponentially with increase in repo size.
>>>>>> 11ty has somewhat less community support.
>>>>>> >>>>>>>
>>>>>> >>>>>>> For choosing an SSG, the choice should be between Jekyll and
>>>>>> HUGO. Jekyll has a somewhat rigid structure whereas HUGO is flexible. I
>>>>>> would recommend HUGO for the task.
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>> Could you explain more about your recommendations, in
>>>>>> particular against 11ty. Also, did you look at any others besides these
>>>>>> three?
>>>>>> >>>>>
>>>>>> >>>>>
>>>>>> >>>>> I looked at Gatsby and Gridsome - the two other main SSGs - but
>>>>>> they are framework dependent i.e. on React and Vue respectively and can be
>>>>>> difficult for those who haven't worked in that area. SSGs like 11ty and
>>>>>> HUGO are easy to learn and setup.
>>>>>> >>>>>
>>>>>> >>>>> Right now, 11ty has lesser community support than HUGO. One pro
>>>>>> of using 11ty is that it can be configured to run in the current directory
>>>>>> structure. Although this can be tempting at first, in my personal
>>>>>> experience, too much flexibility causes a lack of convention and leads to
>>>>>> bad practices. This has been the case of AngularJS which being too flexible
>>>>>> gave way to randomness in conventions. One other advantage is that it can
>>>>>> handle more than just md files, but since all our documentation is in md
>>>>>> format, this isn't of much concern.
>>>>>> >>>>>
>>>>>> >>>>> Therefore I would recommend HUGO. However, I will try to
>>>>>> research more on this topic and will update you if I find HUGO outperformed
>>>>>> by another SSG.
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>>>
>>>>>> >>>>>>> What are your opinions on this?
>>>>>> >>>>>>>
>>>>>> >>>>>>> On Mon, Mar 2, 2020 at 6:27 PM Justin Obara <
>>>>>> obara.justin at gmail.com> wrote:
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Hi Yash,
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> It isn’t required to work on those issues. However, feel
>>>>>> free to triage them and leave comments as necessary (e.g. if they are no
>>>>>> longer applicable and should be closed).
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Other things you could look at in preparation for your
>>>>>> proposal would be:
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> The cross repo event communication you mentioned
>>>>>> >>>>>>>> The current structure, design, and etc.. how that might be
>>>>>> affected by splitting things up
>>>>>> >>>>>>>> Other static site generators, pros/cons for using which ones
>>>>>> >>>>>>>>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Also, regarding your comments about HUGO, if I’m
>>>>>> understanding things correctly, HUGO’s speed benefits are at
>>>>>> build/generation time, not necessarily when viewing the site.
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Feel free to ask other questions you may have.
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Thanks
>>>>>> >>>>>>>> Justin
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> On Mar 1, 2020, at 1:21 AM, Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Also, the issues in the JIRA tracker you shared are very old
>>>>>> and some don't seem to apply now. Should I be working on them?
>>>>>> >>>>>>>>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> On Sat, Feb 29, 2020 at 5:32 PM Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> Hi Justin,
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> Apologies for late reply, was busy with my exams, but they
>>>>>> are gone for good now. I have addressed your comments below.
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> On Wed, Feb 26, 2020 at 8:31 PM Justin Obara <
>>>>>> obara.justin at gmail.com> wrote:
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> On Feb 25, 2020, at 3:36 PM, Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Hi Justin,
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Thanks for the reply. Apologies for the late response from
>>>>>> my side as I am in the middle of my exams. But I'll try to address as much
>>>>>> as I can. I have left them inline.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> On Tue, Feb 25, 2020 at 6:58 AM Justin Obara <
>>>>>> obara.justin at gmail.com> wrote:
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Hi Yash,
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Thanks for your interest in this project. I’ve left some
>>>>>> comments inline below.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Thanks
>>>>>> >>>>>>>>>>> Justin
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> On Feb 24, 2020, at 4:29 PM, Yash Jipkate <
>>>>>> yashjipkate at gmail.com> wrote:
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Hi everyone,
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> I am Yash, and I need some discussion regarding the
>>>>>> project "Refactor and Automating Infusion Documentation" and wanted to get
>>>>>> your opinions on it.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> The HUGO code would be in a different repository; this
>>>>>> would mean that the current repo would have to be cleaned of any rendering
>>>>>> code, just .md and static files would remain. There is a way to clone
>>>>>> another repo into a repo with the help of a script in the CI job.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Yes, ideally the content would be separate so that the
>>>>>> Static Site Generator could be changed if needed, without the need to
>>>>>> modify any of the content. Setting up a CI job, e.g. using GitHub Actions,
>>>>>> could be one possible means of retrieving the content. Although this would
>>>>>> also need to be easily testable for development so would likely involve
>>>>>> some build task that could be run locally as well.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> By testable, do you mean testing the code changes in the
>>>>>> HUGO repo or the changes in the docs repo? Does the docs repo need testing?
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> I’d say both. For example if you make some docs changes,
>>>>>> you’ll want to make sure that it renders correctly, and links to other
>>>>>> pages are functioning. That might involve running an instance of the Static
>>>>>> Site Generator locally. Actually thinking through this process would be
>>>>>> helpful too. It may affect how we make other decisions related to this
>>>>>> project.
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> So I was thinking that we could have a script for local
>>>>>> testing of the docs repo - something like `bash run test.sh` - which would
>>>>>> use the config files of HUGO to run a local instance of docs. We can have
>>>>>> those config files in a tests/ folder. HUGO can be configured to look for
>>>>>> necessary files other than at the root level. We can pull the required
>>>>>> files directly from the remote server rendering repo and delete them or add
>>>>>> them to .gitignore to avoid getting those in the repo.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> The CI should trigger whenever there is a push to main
>>>>>> docs repo; this can be achieved by broadcasting a repository dispatch event
>>>>>> from the main docs repo.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Will another GitHub repo be able to consume the
>>>>>> “repository dispatch event”?
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Yes, the dispatch event is a POST request sent to the repo
>>>>>> we are targeting.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Could you like to the docs for the dispatch event both for
>>>>>> sending and consuming it?
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> You can find them here and here.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> The cloning of the repo can be done tag-wise, i.e.,
>>>>>> instead of cloning the whole repo, cloning just a specific tag(s) would be
>>>>>> done looped over all the available tags.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> That could work. Does that actually save complexity and
>>>>>> time over checking out the whole repo and locally iterating over tags?
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> I guess it would take slightly more time than cloning the
>>>>>> whole repo, but HUGO doesn't have git variables that could extract tags
>>>>>> from it, that's why I came up with this solution.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> There are some libraries for indexing content and
>>>>>> implementing the search functionality like hugo-lunr
>>>>>> >>>>>>>>>>> The front matter - since it is required to not include it
>>>>>> in the files of the main docs repo - can be made as layouts. The only
>>>>>> needed front matter seems to be the title of the page and the GitHub link -
>>>>>> both of which can be determined with the help of FIle Variables in HUGO.
>>>>>> >>>>>>>>>>> The file structure would result as follows: All the .md
>>>>>> documentation files would be having the same organization with their tags
>>>>>> at the topmost level. In other words, the file structure for the .md files
>>>>>> would be content -> <tag> -> <files-in-their =-original-structure>. The
>>>>>> static files would be placed in static/ at the same level as 'content' as
>>>>>> required by HUGO.
>>>>>> >>>>>>>>>>> After cloning a tag, its contents would be copied to
>>>>>> relevant directories, and then the clone would be deleted, and the process
>>>>>> would be repeated for each tag, thus watching changes in each tag.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> These are some of my findings. What are your opinions?
>>>>>> Should this be the way to do it? Or am I missing something that needs to be
>>>>>> addressed?
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> I don’t know for sure if this will work or is the best
>>>>>> solution, but it looks like a good starting point to continue to research
>>>>>> and test from. You can also look into other static site generators if there
>>>>>> are others that may satisfy the requirements better.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Okay, I'll take a look at some other site generators as
>>>>>> well.
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> I think HUGO would be a good fit because of its extreme
>>>>>> speed. In my opinion, a docs site should be as fast as possible since
>>>>>> developers come there mostly when they are searching for something and no
>>>>>> one wants a preloader to take most of their time. What do you think?
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> It would be great if I could get some insight into this.
>>>>>> Also, it would be of great help if I get some guidance on how to start
>>>>>> since the current docs repo has no standing issues on the tracker.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> You can find more issues in the JIRA issue tracker:
>>>>>> https://issues.fluidproject.org/browse/FLUID-6160?jql=project%20%3D%20FLUID%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20component%20%3D%20Website
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Oh, wasn't aware of this tracker, thanks for pointing out.
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> But you should also start by making sure you can get the
>>>>>> current site up and running locally.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Do you mean using docpad? If yes, then I have already done
>>>>>> that.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Yes that’s what I meant.
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> Thanks and Regards,
>>>>>> >>>>>>>>>>> Yash Jipkate
>>>>>> >>>>>>>>>>> Sophomore Undergraduate,
>>>>>> >>>>>>>>>>> IIT(BHU) Varanasi
>>>>>> >>>>>>>>>>> India
>>>>>> >>>>>>>>>>>
>>>>>> >>> <image.gif>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>> _______________________________________________________
>>>>>> >>>>>>>>>>> fluid-work mailing list - fluid-work at lists.idrc.ocad.ca
>>>>>> >>>>>>>>>>> To unsubscribe, change settings or access archives,
>>>>>> >>>>>>>>>>> see
>>>>>> https://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>> Thanks and Regards,
>>>>>> >>>>>>>>>> Yash Jipkate
>>>>>> >>>>>>>>>> Sophomore Undergraduate,
>>>>>> >>>>>>>>>> IIT(BHU) Varanasi
>>>>>> >>>>>>>>>> India
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>>
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>>
>>>>>> >>>>>>>>> Thanks and Regards,
>>>>>> >>>>>>>>> Yash Jipkate
>>>>>> >>>>>>>>> Sophomore Undergraduate,
>>>>>> >>>>>>>>> IIT(BHU) Varanasi
>>>>>> >>>>>>>>> India
>>>>>> >>>>>>>>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Thanks and Regards,
>>>>>> >>>>>>>> Yash Jipkate
>>>>>> >>>>>>>> Sophomore Undergraduate,
>>>>>> >>>>>>>> IIT(BHU) Varanasi
>>>>>> >>>>>>>> India
>>>>>> >>>
>>>>>> >>> <image.gif>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>>
>>>>>> >>>>>>>
>>>>>> >>>>>>> Thanks and Regards,
>>>>>> >>>>>>> Yash Jipkate
>>>>>> >>>>>>> Sophomore Undergraduate,
>>>>>> >>>>>>> IIT(BHU) Varanasi
>>>>>> >>>>>>> India
>>>>>> >>>
>>>>>> >>> <image.gif>
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>> <image.gif>
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>
>>>>>> >>> <image.gif>
>>>>>> >>>>
>>>>>> >>>>
>>>>>> >>>
>>>>>> >>> <image.gif>
>>>>>> >>>
>>>>>> >>>
>>>>>> >>>
>>>>>> >>> --
>>>>>> >>> Thanks and Regards,
>>>>>> >>> Yash Jipkate
>>>>>> >>> Sophomore Undergraduate,
>>>>>> >>> IIT(BHU) Varanasi
>>>>>> >>> India
>>>>>> >>>
>>>>>> >>> <image.gif>
>>>>>> >>>
>>>>>> >>>
>>>>>> >> <image.gif>
>>>>>> >>>
>>>>>> >>>
>>>>>> >>
>>>>>> >>
>>>>>> >> --
>>>>>> >> Thanks and Regards,
>>>>>> >> Yash Jipkate
>>>>>> >> Sophomore Undergraduate,
>>>>>> >> IIT(BHU) Varanasi
>>>>>> >> India
>>>>>> >>
>>>>>> >>
>>>>>> >
>>>>>> >
>>>>>> > --
>>>>>> > Thanks and Regards,
>>>>>> > Yash Jipkate
>>>>>> > Sophomore Undergraduate,
>>>>>> > IIT(BHU) Varanasi
>>>>>> > India
>>>>>> >
>>>>>> >
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Thanks and Regards,
>>>>>> Yash Jipkate
>>>>>> Sophomore Undergraduate,
>>>>>> IIT(BHU) Varanasi
>>>>>> India
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Thanks and Regards,
>>>>> Yash Jipkate
>>>>> Sophomore Undergraduate,
>>>>> IIT(BHU) Varanasi
>>>>> India
>>>>>
>>>>> <image.gif>
>>>>
>>>>
>>>>>
>>>>
>>>> --
>>>> Thanks and Regards,
>>>> Yash Jipkate
>>>> Sophomore Undergraduate,
>>>> IIT(BHU) Varanasi
>>>> India
>>>>
>>>>
>>>>
>>>
>>> --
>>> Thanks and Regards,
>>> Yash Jipkate
>>> Sophomore Undergraduate,
>>> IIT(BHU) Varanasi
>>> India
>>>
>>>
>>>
>>
>> --
>> Thanks and Regards,
>> Yash Jipkate
>> Sophomore Undergraduate,
>> IIT(BHU) Varanasi
>> India
>>
>>
>>
>
>

-- 
Thanks and Regards,
Yash Jipkate
Sophomore Undergraduate,
IIT(BHU) Varanasi
India
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20200318/145e8efd/attachment.htm>


More information about the fluid-work mailing list