Using or merging 'blog' and 'docs' templates together

[cameronelliott]

I have a questions about using 'blog' and 'docs' templates together

I would like to create a site that has both the 'blog' and 'docs' templates, and it seems there are a few basic approaches.

1. Use the repos as-is to create two sites that run on seperate sub-domains. A reasonable approach, except I don't want different sub-domains.

2. Keep the repos as two separate sites, and tweak the build of, say 'docs' somehow (how?) so that it builds to a subfolder, ie '/docs' and hack the header and footer of both sites to be the same, so there is no continuity issues when you move between 'docs' and 'blog'. In this case you would really have two sets of html/css/etc from build output.

3. Merge the repos using careful, careful diffing, editing and merging of common files, and working out how to bring the two templates together, so rather than building two templates and joining the html/css, you have a single template, and actually get a single site output file-set. This seems the least hack-ish, but possibly the most difficult.

I don't have much Php/Laravel/Jigsaw experience (but it's growing), so would some of the maintainers like to weigh-in on the pros and cons and issues of approaches number two and three? Thank you.

Also, do the maintainers think there is a benefit/need to having a single template containing both 'docs' and 'blog', or is the preference to have them stay seperate?

Thank you

[mattstauffer]

I think I would go for 1 or 3.

3 Would be work, but relatively simple work, for someone more familiar with Laravel, so if you are up for it, it would definitely be a good learning experience and produce the best final output.

1 Would be the simplest option, but as you said, you don't want it.

2 Is certainly possible but multiple apps cross building and deploying (even if you were to use symlinks) makes me nervous. Sounds like a recipe for complicated and error-prone bash scripts, sym links, etc.

That's just my gut take though.

[cameronelliott]

@anthonyterrell @damiani @mattstauffer

Great answer, Matt, thanks for your view. If the merged blog ane docs prototype was up-to-snuff, do you think there would possibly be interest in putting it under https://github.com/tightenco ?

I guess what I am asking is your guys opinion on such a work?

The reason I ask, it that I was originally working with Docusaurus, a very nice package, and it offers both a blog and documentation in the same repo/site, something I suspect is very attractive for a lot of folks. (Okay, well, me anyway, lol!)

I decided to switch to Jigsaw because as a video developer who doesn't do web professionally, the whole Tailwind/Jigsaw environment vs React just seemed easier to grok and work with.

Well, I would certainly be interesting in ideas or feedback on what the team & maintainers think about the idea. If I put something together, I will share some links, and see what you guys think of the result.

[cameronelliott]

I used a recursive diff tool (Araxis) to compare my v1.0.4 'docs' against the v1.0.4 'blog' and, like you say, Matt, it seems quite doable, although there is a fair bit of work.

The largest logistical question would be what to do about Algolia vs Fuse/Vue. My long term goal would use site-search, but not either Algolia, or Fuse/Vue, but another offering. But, for a work I can pitch to you guys as a single work of both 'blog' and 'docs' I think the right answer would be to remove Fuse/Vue and just leave Algolia. (Docusaurus went this way too, but I don't know if they index the blog) (The free Algolia offering, DocSearch isn't intended for commercial works or blogs, so, that is a drawback of removing Fuse/Vue, and maybe why blog/docs are split in the first place. Although Algolia will let you run your own indexer for commercial works and blogs, but their messaging is a bit fuzzy. The best long-term answer may be something based on something else, maybe open-source, or mixed open-source commercial, like some elasticsearch stuff, but that's a whole other conversation, probably best for another time)

Of course, you guys may have no interest in a merged blog/docs, which is okay too, its just my particular need. I am just sharing ideas in case there is some interest.

[cameronelliott]

Here is a list of options to Algolia Algolia options

I wouldn't say I have fully checked out everything, but the free up to 2000 documents offering from SearchIQ looks interesting.

[mattstauffer]

I think a merged one is pretty interesting. I'd agree that algolia makes sense and allowing the blog to go un-indexed.

[cameronelliott]

Okay, guys, I am going to take a stab at merging docs and blog, I understand if it isn't right for Tighten, but I think it's the best path forward for my project, but I will keep checking with you guys for input and ideas to end up with something to show you, to see if you think it is interesting for Tighten.

Here is the first thing I would like to ask for some help on: picking a live-reload solution to use with Sizzy...

Here is what I know: You guys mention using Jigsaw/Browsersync in the Jigsaw docs. I am going to try to use Sizzy or Polypane along with Browsersync to compare my merged work as it progresses to the original docs/blog templates. I maybe should have done this for the Tailwind upgrade of docs, but now's a good time to learn.

That will be my main tool for checking success on merging as I go through file by file. I will also be focused on really useful commits, and small chunks when possible to increase transparency, in case you guys do decide to look at something. (who has time for all this? lol!)

I am wondering if you guys have any other suggestions or ideas as I embark on this?